# 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.