roowet-semantic-vault-search: Instructions file for Codex

AGENTS.md — Hermes Agent Integration

For Hermes users: how to wire semantic vault into your agent's init flow. Copy relevant sections to your own AGENTS.md / SOUL.md / CLAUDE.md.

---

MCP Server Config

Add this to your config.yaml:

semantic-vault:
  args: []
  command: python
  connect_timeout: 30
  env:
    VAULT_ROOT: C:/Users/you/path/to/vault
    LANCEDB_PATH: C:/Users/you/data/lancedb
    OLLAMA_BASE_URL: http://localhost:11434
    EMBED_MODEL: bge-m3
  timeout: 60
  working_directory: C:/Users/you/semantic-vault-mcp

Windows note: If python doesn't resolve to the right venv, use a .bat wrapper:

@echo off
call C:\path\to\venv\Scripts\activate.bat
python -m mcp_server.server %*

---

Init Flow Integration

Add these steps to your session init (in SOUL.md or your init protocol):

### Session Init — REQUIRED

1. **`search_vault()`** — semantic context retrieval
   - Query: `"vault structure agent memory error log decisions lessons learned"`
   - Returns: top-10 relevant chunks (~10-15KB)
   - Replaces read_file() for large files

2. **`read_vault_file()`** — if search result needs full context
   - Read specific file from search_vault result
   - Example: `read_vault_file("path/to/file.md")`

3. **`vault_stats()`** — check vault condition
   - Total chunks, unique files, db path

---

Query Classification (Stage 5)

Before any vault lookup, the agent MUST classify the query:

• NO (SIMPLE): general knowledge, chit-chat, obvious answer → answer directly, no search_vault().
• YES (MEDIUM/COMPLEX): project status, past errors, design decisions, concepts, tools, scripts, workflow, user preferences/config → call search_vault() without waiting for the user to say "search the vault".

Flow:

User asks → Stage 5: "Need vault detail?"
  ├── NO → answer directly
  └── YES → search_vault(query)
              → relevant? → answer from vault
              → empty (score < 0.5)? → answer from own knowledge, state "not found in vault"