51 lines
2.5 KiB
Markdown
51 lines
2.5 KiB
Markdown
Kompanion CLI and Schema Navigation
|
||
|
||
This guide shows how to use the `kompanion` CLI to:
|
||
- Configure the database and apply init SQL
|
||
- Call MCP tools directly
|
||
- Run an MCP server (stdio or network) from the CLI
|
||
- Inspect and query the Postgres schema
|
||
|
||
Prerequisites
|
||
- Build: `cmake -S . -B build && cmake --build build -j`
|
||
- Optional: set `PG_DSN` (e.g., `postgresql://kompanion:komup@localhost:5432/kompanion`)
|
||
|
||
Initialization
|
||
- Run wizard and apply DB schema: `kompanion --init`
|
||
- Writes `~/.config/kompanion/kompanionrc` (or KConfig). Also sets `PG_DSN` for the session.
|
||
|
||
MCP Tool Usage
|
||
- List tools: `kompanion --list`
|
||
- Single call with inline JSON: `kompanion kom.memory.v1.search_memory -r '{"namespace":"dev_knowledge","query":{"text":"embedding model","k":5}}'`
|
||
- Read request from stdin: `echo '{"namespace":"dev_knowledge","content":"hello","key":"note"}' | kompanion kom.memory.v1.save_context -i`
|
||
- Interactive loop: `kompanion -I kom.memory.v1.search_memory` then type `!prompt quick brown fox`
|
||
|
||
Run MCP Server from CLI
|
||
- Stdio backend (default): `kompanion --mcp-serve`
|
||
- Explicit backend: `kompanion --mcp-serve stdio`
|
||
- Network backend address (if available): `kompanion --mcp-serve ws --mcp-address 127.0.0.1:8000`
|
||
|
||
Database Navigation
|
||
Note: These helpers expect a reachable Postgres (`PG_DSN` set). If missing, the CLI falls back to an in‑memory stub for tool calls, but DB navigation requires Postgres.
|
||
|
||
- List namespaces: `kompanion --db-namespaces`
|
||
- Output: `name<TAB>uuid`
|
||
- List recent items in a namespace: `kompanion --db-items --ns dev_knowledge [--limit 20]`
|
||
- Output: `item_id<TAB>key<TAB>content_snippet<TAB>tags`
|
||
- Hybrid search within a namespace:
|
||
- Text-only: `kompanion --db-search --ns dev_knowledge --text "pgvector index" --limit 5`
|
||
- With embedding vector from file: `kompanion --db-search --ns dev_knowledge --embedding-file /path/vec.json --limit 5`
|
||
- `vec.json` must be a JSON array of numbers representing the embedding.
|
||
|
||
Schema Guide (Postgres)
|
||
- Tables: `namespaces`, `memory_items`, `memory_chunks`, `embeddings`, `auth_secrets`
|
||
- Key indexes:
|
||
- `memory_items(namespace_id, key)` (unique when `key` not null)
|
||
- `memory_chunks.content_tsv` GIN (full‑text)
|
||
- `embeddings.vector` IVFFLAT with `vector_cosine_ops` (per‑model partial index)
|
||
|
||
Tips
|
||
- For quick trials without Postgres, tool calls work in stub mode (in‑memory DAL). To exercise vector search and FTS, run the DB init scripts via `kompanion --init`.
|
||
- Use `kompanion --verbose` to echo JSON requests/responses.
|
||
|