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: { namespace: string, 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: { namespace: string, 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: { namespace: string, items: Array<{id?:string, text:string, metadata?:object, embedding?:number[]}> }
• output: { upserted: number }

search_memory

Vector + keyword hybrid search.

• input: { namespace: string, 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: { namespace: string, since?: string }
• output: { queued: number }

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.