metal-kompanion/docs/cli-and-schema-navigation.md

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.