List accessible vaults as {name, description} pairs. Response is slim — no metadata (id/role/created_at) — to fit large tenants in agent context. Returns {vaults, total, returned, truncated?, hint?}. Optional args:

• filter: substring match on name+description (case-insensitive). Use to narrow to a domain (e.g. filter='finance').

• limit / offset: pagination when there are many matches.

• include_archived: include archived vaults (default false).

Create a new knowledge base vault (a separate, access-controlled repository for documents). Pass external_git to instead create a read-only mirror of an upstream git repo — the vault tracks the remote on a polling schedule and rejects user writes.

Store a new document. The response carries the canonical uri — akb://{vault}/coll/{collection}/doc/{filename} when stored under a collection, or akb://{vault}/doc/{filename} at the vault root. Use that URI to address the document from every other tool. Automatically chunked and indexed for semantic search.

Retrieve a document by its URI. Returns full content with metadata. Use akb_browse or akb_search first to obtain the URI. Optionally pass a commit hash (from akb_history) to read a previous version.

Update an existing document. Only provide fields you want to change. The content field replaces the complete Markdown body; never pass a partial fragment such as a newly uploaded image. Use a targeted akb_edit for inline insertion or replacement.

Edit a single document by replacing exact text. Scope is one document. old_string must be unique within the document (or use replace_all). If old_string is not found or appears multiple times, the call fails with a clear error. Use this for inserting, replacing, or removing an inline image without resending the complete document body. For find-and-replace across many documents, use akb_grep with replace instead.

Move or rename a document — change its collection and/or slug while keeping its identity and full git history. The old akb:// URI keeps resolving (a redirect is recorded), and graph links/publications are rewritten. Provide collection and/or slug (at least one must change). The title is unchanged; use akb_update to change the displayed title.

Delete a document. Removes from Git, search index, and knowledge graph.

Browse ALL vault content — documents, tables, and files — under a browse root. The browse root can be addressed two ways: pass a canonical uri (akb://V for vault root or akb://V/coll/X for a collection), or the legacy vault + optional collection pair. Use the URI form when drilling down from a previous response — every item carries a uri that can be pasted straight back in.

depth is tree-depth from the browse root, mirroring tree -L N: 0 = direct children only (no descent), N = descend N collection levels, -1 = entire subtree. Collection rows are always emitted as navigation aids regardless of depth.

The response includes metadata for the current browse root in context, and collection items include summary by default so agents understand their intended purpose. Other resource summaries stay opt-in so large vaults fit in the agent's context window. Returns {vault, path, context, items, total, returned, truncated?, hint?}.

Search documents with hybrid retrieval — dense vector (semantic) fused with BM25 sparse (keyword) via Reciprocal Rank Fusion. Handles both natural-language questions and short keyword queries well. For exact string / regex matches (code, URLs, version numbers) prefer akb_grep. Returns each hit's uri; collection_summary and vault_description describe the hit's parent context but do not affect matching or ranking. Use akb_drill_down or akb_get with that URI for full content. Response reports returned (in results) and total_matches (size of the deduped prefetch pool — NOT a corpus-wide hit count; vector ANN is top-K only). When truncated=true the prefetch pool was capped, meaning the corpus may hold more hits than reported — switch to akb_grep with count_only=true for an exact literal-substring count, or refine the query. When degraded=true the retrieval index hit a transient failure (vector-store outage or a degraded leg), so results may be incomplete or empty — this is NOT a genuine zero-match; degradation_reason names the cause. Retry shortly, or fall back to akb_grep for a literal search.

Search for exact text or regex patterns across document content. On a native Document backend, optionally include admitted searchable text Files with measurement_include_text_files=true; binary Files remain excluded. Unlike akb_search (semantic/meaning-based), this finds exact string matches — use it for specific terms, URLs, code snippets, version numbers, etc. Returns matching documents (each with its uri) and matched lines. Optionally pass replace to find-and-replace across all matching documents; the call writes nothing if the scope exceeds max_replacements. Three response shapes (mutually exclusive): default lines, count_only=true (grep -c — per-doc counts + total, no snippets), files_with_matches=true (grep -l — just the URIs that contain the pattern). The default shape always reports BOTH returned_* (what fit under limit) and total_* (full corpus matches) plus a truncated flag. When response safety bounds truncate snippets, the truncation object names the applied resource, match, and byte limits; use count_only for exact counts without snippets.

Read section-level (L3) content of a document, or list its section headings. Two modes:

• mode='sections' (default): return body content of matched sections. Filter with section (heading substring) and/or pattern (substring grep on body). On empty match the response carries an outline so you can retry.

• mode='outline': return heading paths only (no bodies). Use this to discover the document's structure cheaply before deciding which section to read. Returns {uri, sections|outline, returned, total?, truncated?, hint?}.

Get activity history for a vault — who changed what, when, and why. Returns Git commit history with changed file list. Use akb_diff to see the actual content changes for a specific commit.

Get the content diff for a document at a specific commit. Shows what was added/removed/modified. Use akb_history or akb_activity to find commit hashes first.

Get relations for any resource (document, table, or file). Shows same-vault cross-type connections: doc→table, doc→file, table→file, etc. Each row identifies whether it is an explicit link or implicit document-derived edge.

Get a same-vault knowledge graph — nodes (documents, tables, files) and edges (relations). Provide uri to get a subgraph centered on any resource with BFS traversal. Provide vault (without uri) to get the full vault graph.

Create a relation between any two resources (documents, tables, files). Source and target are AKB URIs in the same vault. Relation types: depends_on, related_to, implements, references, attached_to, derived_from. Example: link a design doc to its data table, or attach a diagram file to a spec.

Remove an explicit same-vault relation between two resources. Implicit relations are removed by editing their source document. If relation type is omitted, removes all explicit relations between the two resources.

Get provenance for a document — who created it, when, which entities were extracted, and its visible same-vault relations.

Create a structured data table in a vault. The response carries the canonical uri — akb://{vault}/coll/{collection}/table/{name} when stored under a collection, or akb://{vault}/table/{name} at the vault root. Tables live alongside documents inside collections and follow the same permissions. Define columns with name and type (text, number, boolean, date, json). Optional collection (e.g. 'sessions/learnings') groups the table under that collection so it appears beside the documents and files there in akb_browse; omit for vault root.

Execute SQL on vault tables. Tables are real PostgreSQL tables. Use table names directly (e.g. 'pipeline', 'partners') — they are auto-resolved to the vault's tables. For cross-vault queries, list all vaults in the vaults parameter. Prefix table names with vault name for cross-vault: sales__pipeline, external_projects__partners. SELECT requires reader role. INSERT/UPDATE/DELETE requires writer role. Add a LIMIT to SELECTs unless you truly need every row — the full result set is returned (nothing is silently truncated), so an unbounded SELECT on a large table can send back a very large response.

Permanently delete a table and all its rows. Cannot be undone. Requires admin role on the vault.

Modify a table's schema — add, remove, or rename columns via ALTER TABLE DDL. Requires admin role.

Create a public, no-auth share URL for a document, file, or table query. Document/file: pass the resource uri. Table query: pass query_sql plus vault (and query_vault_names if the query touches more than one). Returns the canonical publication dict — slug is the only identifier you need; share_url is always an absolute URL ready to paste.

Remove publication(s). Pass slug to remove one specific publication, OR uri to remove every publication of that document/file resource (handy when re-publishing). table_query publications have no resource URI, so remove them by slug. Returns {deleted: N}.

List every publication in a vault. Each item is the canonical publication dict (same shape as akb_publish returns).

Freeze a table_query publication's current result to S3 and flip its mode to 'snapshot' (subsequent visits return the cached result). Identified by slug alone — the vault is resolved from the publication. Returns the updated publication dict.

Get detailed vault information: owner, member count, document/table/file/edge counts, last activity.

List all members of a vault with their roles (owner, admin, writer, reader).

Grant vault access to a user. You must be owner or admin of the vault. A rule-driven grantor should name its own source_key so it can later withdraw its own reason without deleting anybody else's.

Revoke a user's vault access. You must be owner or admin. Omit source_key and the person is out of the vault entirely; name one and only that basis is withdrawn, which may downgrade rather than remove.

Explain why a user holds the role they hold on a vault: every independent basis, and the effective role derived from them. A member list shows the result, never the reasons.

Search for users by username, display name, or email. Use this to find users before granting vault access.

Get your current profile — username, email, display name, role. Use this to check who you are authenticated as.

Transfer vault ownership to another user. The current owner or a system admin can do this.

Archive a vault (makes it read-only). Only the owner can do this.

Permanently delete a vault and ALL its data — documents, chunks, tables, files, edges, Git repo. This cannot be undone. Owner or admin only.

Create an empty collection (folder) inside a vault. Idempotent — returns {created: false} if the collection already exists. Writer or higher role.

Delete a collection. If empty, removes the metadata row. If non-empty, requires recursive=true to cascade delete every document, file, and table under the path. Cascade emits one git commit for the document batch. Writer or higher role; admin or higher when any table is included.

Set vault public access level. Owner only. 'none'=private, 'reader'=public read, 'writer'=public read+write.

Get version history of a document — who changed it, when, and why. Each entry is a Git commit. Use the commit hash with akb_get to read a previous version.

Get help on AKB tools and workflows. Call with no arguments for an overview. Drill down into categories or specific tools for details and examples. START HERE if you're new to AKB.

Export an entire vault as a portable knowledge bundle. Returns the bundle inline as a {path: content} map. The format parameter selects the on-disk format — currently 'okf' (Open Knowledge Format: markdown + YAML frontmatter, the only required field being type). Documents export 1:1; tables and files become OKF concept documents (schema / metadata + a resource pointer — the rows/bytes stay in AKB). Reader role required. For a downloadable zip, use the REST endpoint GET /api/v1/vaults/{vault}/export.

Import a knowledge bundle into a vault. Pass files as a {path: content} map (the shape akb_export returns). format selects the bundle format — currently 'okf'. Concept documents are imported as AKB documents; a type: table/file concept doc (which carries only schema/metadata, not rows/bytes) imports as a regular document describing that asset. Existing paths are skipped, not overwritten. Records targeting the reserved 'overview' collection or carrying type='skill' are skipped per-record and reported in the response's 'reserved' list. Writer role required.

Upload a local file to a vault's file storage (S3-backed). Use for PDFs, images, datasets, or any binary content too large for akb_put. Response includes the canonical uri — akb://{vault}/coll/{collection}/file/{uuid} when stored under a collection, or akb://{vault}/file/{uuid} at the vault root — pass that to akb_get_file / akb_update_file / akb_delete_file. MIME type is auto-detected from the filename extension unless overridden.

Upload a local PNG, JPEG, GIF, or WebP (maximum 10 MiB) for inline use in an AKB Markdown document. Returns a stable /api/assets/{uuid} URL and a ready-to-paste markdown image expression. For a new document, place it with akb_put. For an existing document, prefer a targeted akb_edit; akb_update(content=...) replaces the entire body and must never receive only an image fragment. Images are immutable: upload a replacement and edit the Markdown reference. This creates a hidden document attachment, not a standalone File; use akb_put_file when the binary should appear in browse/search. If the document write fails, call akb_discard_image with the returned URL.

Discard a document image upload that was never committed in an AKB document. Use this only to clean up after a failed or abandoned akb_put/akb_update. Images already claimed by a document or retained Git revision cannot be discarded through this tool.

Download a file from vault storage to a local path. Pass the file URI — akb://{vault}[/coll/{coll_path}]/file/{uuid} — from akb_browse or akb_put_file.

Replace the bytes of an existing vault file while preserving its URI. The local file is hashed before transfer; identical content is skipped. Pass expected_content_hash and/or expected_version from akb_get_file to reject stale writes with HTTP 409 instead of overwriting a concurrent change.

Delete a file from vault storage by its URI.