Knowledge

Agor Knowledge is the built-in context layer for your team command center: a central place where humans and agents can store, organize, connect, and find the context that makes work compound over time.

It has everything required to become your team’s main context hub: markdown documents, version history, rich rendering, search, graph links, permissions, and first-class MCP tools for agents. Use it as the source of truth for runbooks, decisions, prompts, teammate memory, and operational knowledge, or as a fast staging area before context moves to another destination. Either way, Knowledge is core to how Agor helps teams and agents accumulate shared understanding.

Context is everywhere: GitHub, Notion, Linear, Slack, repo files, and other knowledge bases. Agor does not ask you to replace all of that on day one. It gives users and agents a durable default place to file the useful bits now, then search, link, reorganize, and reshuffle them later.

Why it matters

A default home for loose context

Agent work produces context constantly: why a branch exists, what a customer said, which deploy caveat matters, how a teammate likes reviews, what a previous agent learned. When there is no obvious repo file or external system for that knowledge, Agor gives everyone a default place to put it.

Shared memory for humans and agents

Knowledge is designed for inter-agent and human/agent collaboration. A human can write a runbook; an agent can search it during a session. One agent can file a decision; another can link to it from a follow-up investigation. Teammates can use it as durable operational memory instead of keeping everything only in branch files or git history.

Zero-config for in-Agor agents

No MCP server setup is required. Knowledge is part of the Agor daemon, and in-Agor sessions already receive the MCP credentials they need. Agents can search, read, write, edit, and publish Knowledge through the same built-in Agor MCP surface they use for branches, sessions, boards, and environments.

What you can store

Knowledge documents are markdown pages grouped into namespaces/spaces. Documents can be tagged by kind (for example doc, memory, skill, prompt, guide, decision, bundle, or external) and can be public or private.

Good fits include:

• Team runbooks: deploy steps, incident notes, review checklists, escalation paths.
• Decisions and rationale: the “why” behind architecture, product, and process choices.
• Reusable prompts and workflows: instructions that agents should reuse instead of rediscovering.
• Teammate memory: durable preferences, project context, operating principles, and daily learnings.
• Scratch-to-structured notes: context filed quickly now and organized more carefully later.

Authoring and rendering

Knowledge uses markdown as the authoring format and Agor’s Streamdown renderer for rich display. That means pages can include the same kinds of content that work well in agent conversations:

• GitHub-flavored markdown and tables
• Syntax-highlighted code blocks with copy controls
• Mermaid diagrams for flows, sequence diagrams, graphs, and architecture sketches
• LaTeX/KaTeX math for technical notes
• Links to other Knowledge documents, including rename-proof agor://kb/document/<id> references

Each content update creates an immutable version, so the page can evolve without losing history.

Search

Text search is always available. Optional semantic and hybrid search become available when a workspace admin enables embeddings in Knowledge → Settings → Semantic search.

Semantic search is intentionally optional: the Knowledge base still works without it, but embeddings make it much more powerful as the corpus grows.

Semantic-search policy is workspace-scoped. Admins choose the enabled state, OpenAI model, chunking, and indexing settings in the Knowledge UI; the provider API key is stored encrypted and is never returned to the browser. Operators do not configure this policy in config.yaml.

The deployment still supplies the underlying capability. Vector search requires PostgreSQL with pgvector available; SQLite can retain workspace settings and build text-search units, but it cannot perform semantic or hybrid vector search.

Upgrading from YAML-based semantic settings: Before restarting Agor, record any values under knowledge.semantic_search, then remove the entire top-level knowledge: block from config.yaml. Agor rejects that removed configuration instead of silently applying one operator policy to every workspace. After startup, a workspace admin can re-enter the policy in Knowledge → Settings → Semantic search. Existing encrypted workspace embedding API keys remain stored and do not need to be copied into YAML.

In required_from_auth deployments, every daemon scans bounded routing metadata across workspaces, then re-enters the selected workspace before reading content, credentials, settings, or vectors. PostgreSQL claims ensure that only one live generation owns a chunk even when several daemons discover it. Distributed scans cap one workspace at 8 chunks per provider batch and 32 candidates per scan; static/single-workspace PostgreSQL preserves the configured 1–128 batch size. SQLite remains text-search-only.

Graph and links

Knowledge is more than a folder of pages. Documents can link to each other, and Agor maintains graph relationships behind those links.

When a Knowledge document contains a resolvable link to another Knowledge document, Agor syncs a references edge in the graph. The Knowledge UI can show a namespace-wide document graph, and MCP tools can fetch neighbors around a document or create explicit graph links.

Content saves replace the document’s outgoing references set, including explicitly created edges of that type. Other edge types are left alone. Removing and restoring a reference preserves its edge identity and metadata. Graph maintenance is best-effort: if it fails, the document still saves and the previous graph remains intact until a later successful content save.

Use links when you want agents to understand relationships such as:

• A runbook references a decision record.
• A prompt depends on a style guide.
• A memory entry is about a branch, task, or artifact.
• A new investigation supersedes an older note.

For durable cross-document references, prefer the rename-proof document URI that agents receive from search/get results: agor://kb/document/<documentId>.

Agent workflows over MCP

Knowledge has first-class MCP tools, so agents can use it without leaving their session.

Common workflows:

• Browse, search, and load context with agor_kb_tree, agor_kb_search, agor_kb_get, agor_kb_outline, and agor_kb_get_range. Use agor_kb_tree({ namespace, pathPrefix?, depth? }) for the common “show me what is in this namespace” request. It returns a compact folder/document tree with icon, title, kind, path, URI, reference URI, and status only. No document content or version metadata. agor_kb_search is optimized for query discovery: non-empty searches return metadata plus short snippets by default, while browse/listing calls with query: "" return metadata only. Use contentMode: "none" | "snippet" | "full" and snippetLines to control result verbosity, and prefer agor_kb_get or agor_kb_get_range when you need to read document content. For large markdown docs, use agor_kb_outline as the map: it returns heading titles, line ranges, compact size hints, duplicate-heading occurrences, and sectionRef selectors such as root.h1[1].h2[2]. Then call agor_kb_get_range with that sectionRef (or a line range / headingPath + occurrence) to read only the needed section with nearby context. For very large sections, page through the selected section with offsetLines and maxLines.
• File new context with agor_kb_put when an agent discovers something worth keeping.
• Make targeted edits with agor_kb_edit, including version checks and dry runs.
• Round-trip through a worktree with agor_kb_materialize and agor_kb_publish_from_worktree, where branch permissions allow local workspace access.
• Inspect history with agor_kb_history.
• Connect the graph with agor_kb_link and agor_kb_graph_neighbors.

This makes Knowledge a natural companion to Teammates: teammates can still keep file-based identity and memory where that is useful, while using Agor Knowledge as shared, searchable operational memory for the whole workspace.

Archive and restore

Use Archive on a page to hide it from active lists, search, mentions, graphs, and teammate context. Select Archived pages in the browser to find it again, then Restore in the archived-page banner. Authorized direct links and history still work. Archive/restore requires the document owner or an admin, plus namespace write access; public editing alone is not enough.

Archival preserves the document ID, content, versions, visibility, ownership, and grants. Restore does not create a content version. Archived paths stay reserved: ordinary upsert/edit cannot restore or replace an archived document. Restore first. For older archives whose path has an active replacement, rename that replacement before restoring by document ID.

• MCP: agor_kb_archive({ documentId, archived: true }); use false to restore. agor_kb_archive_bulk({ archived, targets: [{ documentId }] }) accepts 1–50 explicit targets. Each item is authorized and committed independently; results identify failures without exposing inaccessible documents. Retry the same targets safely.
• Discovery: archiveFilter: "active" | "archived" | "all" on MCP search/tree; archive_filter on API document lists/search. Default: active. Legacy search includeArchived/include_archived: true means all; list archived: true means archived-only. Permissions always apply. Graphs and automatic context stay active-only.
• API: metadata-only PATCH /kb/documents/:id with { "archived": true } or false. Optional expected_version and expected_archived guards reject stale transitions (409); already-satisfied retries are no-ops, including timestamps. MCP uses expectedVersion/expectedArchived per target. DELETE remains soft archive.
• CLI: agor kb document list --namespace team-docs --archive archived (or all). Direct document get can read authorized archives.

These controls archive documents, not namespaces. Existing namespace archival still archives its documents; an archived namespace is not bypassed by these filters or by document restoration.

Permissions and control plane fit

Knowledge is tied into Agor’s existing role-based control plane. Members can create and work with documents and namespaces, workspace admins manage semantic-search settings, and namespace owners/admins manage namespace governance. Each document also carries visibility and edit-policy controls.

Teammate daily memory documents (memory/YYYY-MM-DD.md, written by agor_teammate_memory_append) are created private with owner-only editing, whatever the teammate namespace’s default visibility is. Only the user whose session created that day’s document, and admins, can read or append to it. The document owner can widen an individual document afterwards. To change the creation default for a teammate, set memory_visibility and/or memory_edit_policy in the teammate’s custom_context.teammate.kb config. Memory documents that already exist keep their current settings.

In practice, that means Knowledge follows the same posture as the rest of Agor: humans and agents collaborate in one system, with view/edit boundaries enforced by the daemon rather than scattered across ad hoc files and local MCP servers.

Discover and inspect Knowledge with the CLI

The read-only commands use your connected deployment and normal Knowledge read permissions; they do not require export-admin access or write Knowledge data.

agor kb namespace list
agor kb namespace show team-docs
agor kb document list --namespace team-docs
agor kb document list --namespace team-docs --status draft
agor kb document get index.md --namespace team-docs

Lists default to 50 rows, sorted by namespace slug or document path. Use --limit 20 --offset 20 for the next display page. The footer reports N of X accessible active entries, with the displayed range. Empty and out-of-range pages report zero displayed rows. These existing APIs return the complete authorized metadata inventory: pagination limits display, not server-side retrieval. Document lists include every draft you are allowed to read, omit archived documents, and do not fetch Markdown bodies. Counts can change between invocations and are not a snapshot or a count of inaccessible documents.

All four commands accept --json. Lists emit { total, limit, offset, data }; namespace show emits namespace details; document get emits metadata, current version, and content. Without --json, document get writes only current Markdown to stdout, preserving content when piped or redirected. Interactive terminal output escapes control characters. Paths are logical Knowledge paths, including .md when stored that way, not local filenames. Read these details before exporting and again after importing to spot-check the destination. These four commands are read-only.

Move a namespace with the CLI

Use agor kb export and agor kb import to migrate current markdown documents between deployments. Every run plans its work first. The CLI reads stored SHA-256 hashes without downloading document bodies, hashes local files, and transfers only needed content. Planning, copying and reference reconciliation each show progress; once planning finishes, the action total is fixed.

# Log in to the source deployment as a workspace admin.
agor login --url https://source.example
agor kb export --namespace team-docs --output ./team-docs-export --dry-run
agor kb export --namespace team-docs --output ./team-docs-export
 
# Move the entire directory if the destination CLI runs on another machine.
agor login --url https://destination.example
agor kb import ./team-docs-export --namespace migrated-docs --dry-run
agor kb import ./team-docs-export --namespace migrated-docs --apply

Import defaults to planning only; --apply is required for writes. Export writes by default and creates the output directory with mode 0700. Existing output directories must be private and owned by the CLI user. Export and import run on Linux and macOS; on Windows, use WSL. The CLI does not write files on the daemon or require an Agor session, S3 or a background migration job.

Typical progress looks like:

Plan: 240 documents; 200 unchanged; 40 fetch/verify; 81920 known bytes; 0 unknown hashes
Exporting: 17 / 40 34816 / 81920 bytes | elapsed 3s

Human progress goes to stderr; the final JSON summary goes to stdout. Redirected terminals receive periodic newline updates instead of an animated progress line. During discovery, counts describe the current scan, not a transactionally frozen snapshot. A legacy version without a stored hash is planned as fetch/verify, never assumed unchanged. Indexing may continue after the CLI finishes.

Scope and ownership

Export requires workspace-admin access so it can include all active documents, including private documents and other authors’ drafts. Import requires member access and creates a new, private namespace owned by the importing user. Documents are private with owner-only editing. Titles, icons, kinds, draft/published status and separate frontmatter are retained. Original metadata, author facts and timestamps are kept as inert provenance; destination attribution records the actual import. Source ACLs, owners, admin roles and repo/branch bindings are never applied. Review the result before sharing the destination namespace.

Git-friendly repository format (version 2)

Exports use readable folders and YAML metadata:

team-docs/
  manifest.yaml
  docs/
    guides/getting-started.md
    incidents/parent-session-not-notified.md
  .agor/                 # local checkpoint, snapshot and refresh state; Git-ignored
  .gitignore
  .gitattributes

manifest.yaml contains the format/version, namespace information, omissions and a sorted list of expected Markdown files. Each document has a generated YAML header with format, version, agor (stable UUID, logical path, title, icon, kind and status), separate user frontmatter, and inert provenance. Fields are indented and sorted consistently. The Markdown body follows the header. Existing body frontmatter, prose metadata such as “Date · Reporter”, and line endings are not reformatted. Only supported Markdown link destinations are transformed.

Physical paths mirror Knowledge paths where possible. Extensionless documents get .md filenames; case/Unicode collisions, file/folder conflicts, hidden components and long names receive deterministic suffixes. Existing mappings are retained on refresh. The header’s agor.path is the authoritative logical Knowledge path; renaming a file alone does not rename the document. Document identity lives in the full agor.id, not in a short-ID filename suffix.

You can edit bodies and supported metadata in Git without updating checksums. Import computes a canonical plan from current content, independent of YAML key order, comments or indentation. An edit changes that plan: it can be imported into a new namespace, but it cannot resume a different plan into an existing one. Repeated publishing into an existing namespace is not a synchronization feature of this format. Source ACLs, tenant IDs and author identities never confer authority.

For deliberate additions/removals, update the documents list in manifest.yaml. New documents require a unique UUID and a valid version 2 header. Missing listed files fail validation. Unlisted Markdown under docs/ is reported and never imported; deleting a local file never deletes a destination document.

Validate locally without logging in, contacting a daemon or writing files:

agor kb validate ./team-docs-export

The JSON result reports document/body totals, the semantic bundle fingerprint, unresolved links and unlisted files. YAML accepts bounded JSON-compatible values; duplicate keys, aliases, tags, merge keys and excessive nesting are rejected with sanitized errors. Keep dates/IDs as strings. Import also checks encoded HTTP request limits using the selected destination namespace before any import writes.

Known internal Agor links become relative Markdown links for repository browsing. Import translates indexed local targets back into destination Knowledge references, including fragments and reference definitions. Code and ordinary prose are not rewritten. External links and unsupported escaped destinations may need manual review; uploaded images/assets are not downloaded or made portable.

A Git clone needs only the tracked manifest and documents for import. Do not commit .agor/ or .agor-lock/: the former holds source identity, immutable source snapshots, previous content and refresh checkpoints. Generated .gitattributes keeps Markdown bytes unchanged during Git checkout. Existing Git control files are retained rather than overwritten; the CLI reminds you to configure their ignore and line-ending rules yourself.

Export refresh requires the original local baseline and refuses to overwrite local edits or untracked files. A clone without .agor/ is importable, but refreshing it requires a fresh export directory. Removed/renamed source documents may leave old unlisted files behind; refresh does not prune them. Review retained/unlisted results and use a fresh directory for a minimal handoff. Full-fidelity exports can include private documents, drafts and author/provenance details: readable filenames and Git ignore rules do not make them safe to publish to a public repository.

Version 1 manifest.json bundles are not accepted by this repository reader and are never converted in place. Use a fresh export with a CLI supporting repository format v2; preserve old bundles until the new export is verified. The on-disk version changed; the bounded transfer HTTP protocol and daemon authorization rules did not.

This is not a full backup or bidirectional sync. It excludes historical versions, archived documents, manually authored graph edges, asset bytes, grants and semantic search settings/credentials. Images and external/upload/branch-file references are not fetched and may not remain available after moving. Source UUIDs are provenance, not destination authority. There is no email-based ownership matching.

Resume, conflicts and limits

agor kb export --namespace team-docs --output ./team-docs-export --resume
agor kb import ./team-docs-export --namespace migrated-docs --resume --apply

Cancellation stops scheduling new work; a request already in flight may finish. Imports retain committed documents. Durable, caller-bound receipts make a lost acknowledgement safe to retry: unchanged entries are skipped without new revisions. Renamed, edited or archived imported documents cause a conflict, not recreation. An unrelated existing namespace is never merged or overwritten. A modified bundle is a new import and needs a new destination namespace. Keep the destination private and unchanged until import and reference reconciliation finish.

Each namespace creation, document write and reference reconciliation is its own short database transaction. A document and its resume receipt commit together; a failed document transaction does not roll back earlier documents.

Export/import continue to other documents after classified document-level failures (such as a missing source version, checksum mismatch, document conflict or HTTP 500). Import reference-check failures likewise do not block the remaining reference checks. The command still exits unsuccessfully and reports acknowledged/cached progress, failed or unconfirmed counts, and up to 20 sanitized error details. Details identify the plan key and source document UUID, rather than printing private content or titles. A failed POST may already have committed: resume consults server receipts rather than blindly creating it again.

Errors are not silently skipped out of the bundle. An incomplete export retains verified source files/checkpoints but publishes no new completed repository; a failed refresh leaves the prior readable snapshot unchanged. Import defers its final reference-reconciliation pass until every planned document is available. Resume retries missing documents and outstanding reference checks, without duplicating completed revisions. Resolve permanent errors first; if fixing local files changes the bundle, use a new destination namespace. An incomplete first export still requires a fresh output directory if the source inventory changes.

Authentication/permission failures, rate limits, unavailable services, transport failures, unrecognized request-schema errors, namespace-wide limits, unreliable inventory, cancellation and unsafe local files stop further work. There is no blind automatic network retry loop. Import validates the entire local repository before writes: malformed headers or a missing indexed file do not authorize importing an implicit subset. Successful prior work remains retained even when a fatal error stops the run.

If planning stops with Invalid Knowledge transfer request, do not repeatedly retry with --apply. Transfer errors identify the stage, HTTP method/route and sanitized invalid fields when the daemon supplies them. Compare agor --version with the destination’s public /health version to investigate compatibility; the error alone does not prove a version mismatch. Transfer inventories use cursor pagination, not $limit/$skip, and --namespace takes a slug, not an ID.

After resolving the reported error, validate without import writes:

agor kb import ./team-docs-export --namespace migrated-docs --resume --dry-run

This reads the bundle and destination transfer receipts; it does not change local checkpoints or destination documents. A 0 discovered progress line is emitted before the first inventory response and is not evidence that the destination is empty or that an earlier attempt committed nothing. Keep the bundle and checkpoints intact. When reporting a failure, share CLI/daemon versions and the sanitized stage/field diagnostic, not credentials, request bodies or private docs.

An interrupted source snapshot can resume against the same source inventory. Completed source snapshots can be refreshed. Independently altered cache files are rejected, not overwritten. The export lock renews while the CLI runs; after a hard exit allow 30 seconds for a stale lock to become reclaimable.

Readable-file publication is staged and journaled. An interruption after publication begins blocks local import/validation until agor kb export ... --resume completes it. Resume verifies staged hashes and refuses intervening local edits. Before this publication phase, a failed refresh leaves the prior readable snapshot unchanged. A successful no-change refresh does not rewrite tracked documents or the manifest. Do not commit or copy the tree while an export is running or publication is incomplete: a clone without ignored recovery state cannot detect a partially committed refresh. This editable format is not a sealed backup archive.

Export verifies source body hashes and compares source inventory before accepting its local source snapshot. This is not a point-in-time namespace snapshot; keep the source quiet during migration. Deliberately edited repository files are editable source, not a claim that their bytes still match the original export. Import checks for local changes between planning and applying; existing destination receipts and no-overwrite conflicts remain authoritative.

Limits are 10,000 documents, 10 MiB per body, 100 MiB total body bytes, a 10 MiB manifest and 10 MiB aggregate serialized document headers, a 9 MiB encoded import request (below the daemon’s HTTP JSON ceiling), and 110 MiB across all encoded document requests. Import planning checks the full rewritten plan, including JSON escaping and metadata, before creating the namespace. Excessive nesting, unsafe filenames, symlinks, hardlinks, invalid UTF-8 and mismatched source/staging hashes fail closed. Archive extraction is not supported.

When to use Knowledge vs. repo files

Use repo files when the context is part of the product itself: source-adjacent docs, checked-in configuration, prompts that should review with code, or teammate framework files that belong to a branch.

Use Knowledge when the context should be easy for the whole Agor workspace to find, update, link, and reuse across branches, sessions, teammates, and people.

Most teams will use both. The important thing is that useful context has somewhere durable to land.