local-rag-core: Instructions file for Codex

AGENTS.md — local-rag-core

MCP Integration

This project's knowledge base is served by its own MCP server. Before modifying any code, query the knowledge base:

kb.health       — check system status and backend health
kb.list_packs   — see available knowledge packs
kb.search       — search across private_kb and packs
kb.get_chunk    — retrieve full chunk content

Required Pre-Modification Workflow

Before proposing or implementing any code change:

1. Query project goals:

   kb.search "local-rag-core project purpose and design goals"
   

2. Check current status:

   kb.health
   kb.list_packs
   

3. Retrieve relevant decisions:

   kb.search "<your specific topic>"
   

4. Identify no-modify zones:

   • Do NOT modify knowledge base data through MCP (read-only by design)
   • Do NOT modify storage/, data/packs/, data/private_kb/ directly
   • Do NOT bypass the pack lifecycle (use CLI for build/export/import)
   • Do NOT change the MCP tool schema without updating this file

5. Summarize retrieved context before proposing changes.

Architecture Boundaries

• MCP is read-only. All writes go through CLI (rag ...) or HTTP API (with X-Local-RAG-Token auth).
• Three knowledge zones: private_kb (user's), packs (shareable), private_project (code repos with filters).
• Backend status: Check rag health for mock vs real backends.
• Model cache: HuggingFace default at E:\AI\huggingface\hub\. Override with LOCAL_RAG_MODEL_CACHE.

Key Commands

rag health                              # system health
rag pack list                           # registered packs
rag search "<query>" --mode hybrid      # hybrid search
rag chunk get <chunk_id>                # retrieve chunk
pytest && ruff check .                  # validate before commit

Project Status

See PROJECT_STATUS.md for current phase and capability boundaries.