agent-knowledge: Instructions file for Codex

AGENTS.md

Project guide for AI agents (Claude Code, Codex, Cursor, custom agents). Human readers should start at README.md.

What this project is

agent-knowledge is long-term memory and a knowledge base for AI agents: raw conversations and documents → Claim + Evidence extraction → merged into Compiled Truth → append-only timeline. Every fact is traceable to source, timestamp, and confidence, with contradiction detection on top.

Position: it is compiled memory — not RAG, not a KV preference cache.

When you (an agent) should use it

• The user asks "why did we decide X back then?" — needs timeline and decision context
• Multiple sources about the same entity need to be merged and reconciled
• Facts need to persist across sessions (user preferences, project conventions, prior decisions)
• The answer must be explainable with source provenance, not just "vector similarity"

Skip it for:

• One-shot retrieval (plain RAG is lighter)
• Real-time event streams (this is the knowledge layer, not an event bus)

Quickest path to use

Option 1: MCP server (recommended for agent integration)

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "ak",
      "args": ["mcp", "/absolute/path/to/vault"]
    }
  }
}

Drop this into .claude/settings.json, .cursor/mcp.json, or any MCP-aware client config. Full tool list is in docs/mcp-integration.md.

Option 2: CLI

compiled-memory is the PyPI distribution; agent_knowledge is the Python module.

pip install compiled-memory
ak init   /path/to/vault
ak ingest /path/to/vault --file notes.md
ak query  /path/to/vault "why did we pick React?"

Option 3: Python API

from agent_knowledge import Vault, Compiler, SearchEngine

vault = Vault("/path/to/vault")
vault.init()

compiler = Compiler(vault)
compiler.ingest("We picked React over Vue.", title="Frontend decision")

engine = SearchEngine(vault)
for hit in engine.search("why React?", top_k=5):
    print(hit.title, hit.score)