Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Document upload

Tools for ingesting whole files (markdown, code, PDFs, spreadsheets, images, etc.) into memory with automatic chunking and abstraction.

upload_document

Upload a file from the server’s local filesystem. The server reads the file, splits it into chunks, embeds each chunk, and stores them as L0 memories. The L0→L1 worker then creates summaries in the background.

Input

FieldTypeRequiredDescription
file_pathstring✓Absolute path to the file. Must be readable by the server process.
file_namestringOptional name (defaults to the basename of file_path).
mime_typestringOptional MIME type (default text/plain).
chunk_sizeintegerOverride document_chunk_size.
process_immediatelybooleanStart processing after upload (default true).
topicsarrayTopics applied to all chunks.
contextarrayContext tags applied to all chunks.
event_atstringISO 8601 for when the document’s events occurred. Defaults to upload time.
bankstring
user_id / agent_idstring

Output

The response is not schema-constrained. A representative shape:

{
  "success": true,
  "data": {
    "session_id": "uuid",
    "file_name": "architecture.md",
    "chunks_stored": 23,
    "memory_ids": ["uuid-a", "uuid-b", "…"]
  }
}

Limits

upload_document is best for small to medium files (up to a few MB). For very large files (10s of MB+) or files you already have in memory, use the ingest tool, or the CLI’s multi-part upload flow (begin-upload / upload-part / process-document, see CLI commands).

ingest

Universal decomposition entry point. Takes raw content (a string, or base64 for binary) and automatically detects the format, decomposes it into semantic L0 chunks, creates structural relations between chunks, and optionally auto-links to existing memories.

Unlike upload_document, this does not read a file from disk — you pass the content directly. For binary formats (PDF, DOCX, images), base64-encode the content and set content_encoding: "base64".

Input

FieldTypeRequiredDescription
contentstring✓Raw content. For binary formats, base64-encoded.
content_encodingstring"base64" for binary formats.
format_hintstringOptional hint: markdown, json, yaml, toml, text.
file_namestringFor extension-based detection and provenance.
bankstring
auto_linkbooleanAuto-link chunks to existing memories (default true).
generate_abstractionsbooleanGenerate L1+ interpretations (default true).
max_chunk_sizeintegerMax characters per L0 chunk (default 2000).
metadataobjectMetadata attached to all chunks.
sourcestringOverride the auto-derived source (e.g. a URL or DOI).
describe_imagesbooleanGenerate AI descriptions for images (default true; requires a vision-capable LLM).

Output

{
  "success": true,
  "message": "…",
  "data": {
    "status": "success",
    "session_id": "uuid",
    "format": "markdown",
    "detected_mime": "text/markdown",
    "byte_size": 45678,
    "l0_chunks": [
      { "id": "chunk-0", "memory_id": "uuid", "node_type": "text", "content_preview": "…", "char_count": 1980, "order": 0 }
    ],
    "relations": [
      { "source_chunk_id": "chunk-0", "target_chunk_id": "chunk-1", "relation": "next_chunk", "strength": 1.0 }
    ],
    "issues": [],
    "warnings": [],
    "format_hints_available": ["markdown", "text"]
  }
}

document_status

Check the status of a document upload session.

Input

FieldTypeRequiredDescription
session_idstringSpecific session. If omitted, lists all sessions.
bankstring

Output (specific session)

{
  "success": true,
  "data": {
    "session_id": "uuid",
    "file_name": "large.pdf",
    "status": "processing",
    "chunks_processed": 42,
    "chunks_total": 100,
    "started_at": "...",
    "completed_at": null,
    "error": null
  }
}

cancel_document

Cancel an in-flight upload or processing session.

Input

FieldTypeRequiredDescription
session_idstring✓
bankstring

Output

{
  "success": true,
  "message": "Session 'uuid' cancelled",
  "data": { "session_id": "uuid" }
}

Document storage

Documents themselves are not stored in the bank. Only the chunks (after parsing) and the session state are kept. To keep the original file, store it elsewhere or use the db export flow to capture both the bank and the session database.

Next