Files and categories
Document workspace files for recall with /v1/files, and control which memory types consolidation promotes with /v1/categories.
| Method | Path | Capability |
|---|---|---|
GET | /v1/files/{workspaceId} | read |
POST | /v1/files/document | write |
POST | /v1/files/search | read |
GET | /v1/categories/{workspaceId} | read |
POST | /v1/categories/{workspaceId} | write |
DELETE | /v1/categories/{workspaceId}/{categoryId} | write |
File documentation
File documentation gives agents a map of a codebase without re-reading it. You send file contents; the platform extracts structural metadata (namespace, classes, methods, imports, exports) and, for new or significantly changed files, generates a summary (with the configured LLM, when one is available) and a purpose line. Files whose content changed only slightly keep their summary and get fresh metadata. Relevant files appear in recall under fileDocs.
A documented file looks like:
{
"id": "…",
"workspaceId": "…",
"filePath": "src/UserService.cs",
"fileType": "cs",
"fileSize": 4210,
"contentHash": "…",
"lastModified": "2026-10-01T09:00:00Z",
"lastDocumented": "2026-10-01T09:00:00Z",
"namespace": "Acme.Users",
"classNames": ["UserService"],
"methodNames": ["CreateAsync", "DeleteAsync"],
"imports": ["System"],
"exports": [],
"summary": "…",
"purpose": "…",
"dependencies": [],
"patternsUsed": []
}List documented files
GET /v1/files/{workspaceId} — returns every documented file in the workspace.
Document files
POST /v1/files/document — document a batch of files (at most 50 per request; more answers 422).
{
"workspaceId": "…",
"files": {
"src/Program.cs": "using System;\n…",
"src/UserService.cs": "public class UserService { … }"
}
}Response: { "documented": 2 } — the number of files actually documented, not the number requested. Request bodies are limited to 1 MiB by default, so batch large codebases.
Search files
POST /v1/files/search — find files by what they do (semantic, not path matching).
{ "workspaceId": "…", "query": "user authentication", "topK": 5 }topK is clamped to 1–50 (default 5). MCP: search_files.
Semantic categories
Semantic categories decide which session entries consolidation extracts into durable facts. Each category lists the memory types it promotes and can carry an extraction prompt that steers fact extraction for those entries.
When a workspace has no categories, the first consolidation seeds these defaults:
| Name | Promotes |
|---|---|
corrections | correction |
violations | violation |
approved_patterns | approved_pattern |
decisions | decision |
conversation | raw |
preferences | preference |
artifact_ref is not promoted by default. A type that no enabled category lists is recorded as an episode event but not extracted into facts.
List categories
GET /v1/categories/{workspaceId} — returns the workspace's enabled categories, ordered by name:
[
{
"id": "…",
"workspaceId": "…",
"name": "corrections",
"description": "Error corrections and fixes",
"promotableTypes": ["correction"],
"extractionPrompt": null,
"isEnabled": true,
"createdAt": "…",
"updatedAt": "…"
}
]Create or update a category
POST /v1/categories/{workspaceId} — upsert. Omit id to create; pass an existing id to update.
{
"id": null,
"name": "security_findings",
"description": "Security issues found during review",
"promotableTypes": ["violation", "correction"],
"extractionPrompt": "Extract each security issue as one self-contained fact.",
"isEnabled": true
}Returns the stored category. Set isEnabled: false to disable a category without deleting it.
Delete a category
DELETE /v1/categories/{workspaceId}/{categoryId} → 204.