58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# 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 }`
|
|
|
|
### `sync_semantic`
|
|
Promote episodic rows into semantic (chunks + embeddings) storage.
|
|
- input: `{ namespace: string, 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.
|