metal-kompanion/docs/mcp-memory-api.md

MCP Memory/Context API for Kompanion

Goals

• Persist long-term context across threads/sessions.
• Provide embeddings + retrieval over namespaces (project/user/thread).
• Expose via MCP tools with JSON schemas; versioned and testable.

Tools

save_context

Persist a context blob with metadata.

• input: { key?: string, content: any, tags?: string[], ttl_seconds?: number }
• output: { id: string, created_at: string }

recall_context

Fetch context by key/tags/time range.

• input: { key?: string, tags?: string[], limit?: number, since?: string }
• output: { items: Array<{id:string, key?:string, content:any, tags?:string[], created_at:string}> }

embed_text

Return vector embedding for given text(s).

• input: { model?: string, texts: string[] }
• output: { model: string, vectors: number[][] }

upsert_memory

Upsert text+metadata into vector store.

• input: { items: Array<{id?:string, text:string, metadata?:object, embedding?:number[]}> }
• output: { upserted: number }

search_memory

Vector + keyword hybrid search.

• input: { query: { text?: string, embedding?: number[], k?: number, filter?: object } }
• output: { matches: Array<{id:string, score:number, text?:string, metadata?:object}> }

warm_cache

Precompute embeddings for recent items.

• input: { since?: string }
• output: { queued: number }

sync_semantic

Promote episodic rows into semantic (chunks + embeddings) storage.

• input: { max_batch?: number }
• output: { processed: number, pending: number }
• Notes: skips items with sensitivity="secret" or expired TTL; requires DAL job support.

Auth & Versioning

• toolNamespace: kom.memory.v1
• auth: bearer token via MCP session metadata (optional local mode).

Error Model

{ error: { code: string, message: string, details?: any } }

Events (optional)

• memory.updated broadcast over MCP notifications.

Notes

• Namespaces: project:metal, thread:<id>, user:<id>.
• Store raw content and normalized text fields for RAG.
• Resource descriptors live under resources/memory/kom.memory.v1/ (episodic, semantic, and sync jobs) to align MCP tooling with DAL schema.