Shared knowledge

Beyond its own memory, an agent can read and contribute to shared knowledge scoped to the org, teams, and projects it belongs to. This is knowledge about the things being worked on — a project’s docs, a team’s facts, an org’s profile — and it’s the deliberate boundary across which agents on the same account learn from each other.

Membership is enforced on the server for every call: an agent only ever sees scopes it’s a member of, and writing to a scope it isn’t a member of is rejected. All examples use the @alfe.ai/agent-api-client.

Discover your scopes

There’s no implicit “current” scope — an agent sees the full set it belongs to and passes an explicit scopeId on every call. Start by listing them:

knowledge.ts

const { scopes } = await client.listScopes();
// GET /agent/org/scopes
// scopes: [{ scopeType: "org" | "team" | "project", scopeId, name }]

For the org scope, scopeId is the tenant id — take it from this list rather than constructing it.

Search across scopes

Semantic search fans out across the agent’s member scopes. Narrow to one scope by passing scopeType + scopeId.

const { results, truncatedScopes } = await client.knowledgeSearch(
  "what's our refund policy?",
  { limit: 10 },
);
// POST /agent/knowledge/search

{
  "data": {
    "results": [
      {
        "id": "…",
        "text": "Refunds are issued within 14 days…",
        "score": 0.78,
        "scopeType": "project",
        "scopeId": "…",
        "source": "doc",
        "filePath": "policies/refunds.md"
      }
    ],
    "truncatedScopes": false
  }
}

Each hit is either a doc (with a filePath) or a fact (with a factId).

Profiles

Read a scope’s structured profile — a short “about”, a description, and links.

const profile = await client.getScopeProfile("project", scopeId);
// GET /agent/org/profile/{scopeType}/{scopeId}

Facts

Facts are concise, attributable statements. List, publish, and delete them:

const { facts } = await client.listScopeFacts("team", scopeId, { limit: 50 });
// GET /agent/org/facts/{scopeType}/{scopeId}

const fact = await client.createScopeFact("team", scopeId, "We deploy on Tuesdays.");
// POST /agent/org/facts/{scopeType}/{scopeId}

await client.deleteScopeFact("team", scopeId, fact.factId);
// DELETE /agent/org/facts/{scopeType}/{scopeId}/{factId}

Publishing a fact is a deliberate act — the agent is recorded as the author, and it’s never an automatic merge into someone else’s knowledge.

Docs

Docs are the shared file corpus for a scope. List them, read one’s full text, and write (create or overwrite) one:

const { files } = await client.listScopeDocs("project", scopeId);
// GET /agent/org/files/{scopeType}/{scopeId}

const { text } = await client.readScopeDoc("project", scopeId, "policies/refunds.md");
// resolves a download URL, then fetches the bytes

await client.writeScopeDoc("project", scopeId, "policies/refunds.md", updatedText, {
  contentType: "text/markdown",
  message: "Clarify the 14-day window",
});
// resolves an upload URL, then PUTs the bytes

Authorship on a written doc is set from the agent’s token on the server — it’s never trusted from the client.

Related

• Memory — the agent’s own private, per-agent memory.
• Workspace sync — backing up the agent’s own files.