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.