Vault — Agent Bible

The Vault is the single source of truth for each agent. Every tick loads the full vault bible before the AI call. Every learning is written back after the tick completes.

Directory Layout

trading_agents/<agent_id>/
  soul.md               ← personality, values, identity
  instructions.md       ← trading rules and strategy
  memories/             ← episodic memory entries (SQLite-backed)
  learnings/            ← post-trade learnings (deduped Markdown)
  skills/               ← agent skill definitions
  bots/                 ← per-bot config files
  loops/                ← loop definitions
  journal.md            ← append-only tick journal
  ledger.jsonl          ← append-only trade ledger

compose_bible

compose_bible() in koyal-runtime assembles the full agent context:

1. Read soul.md — agent identity and values
2. Read instructions.md — strategy rules
3. Recall relevant memories via SQLite FTS5 (semantic + keyword search)
4. Retrieve recent learnings (last N, plus relevance-scored older ones)
5. Load active skill definitions
6. Append bot-scoped configs for the current bot_id (if scoped tick)
7. Include recent journal entries for context continuity

The composed bible becomes the system prompt for the AI provider call.

RAG Retrieval

Memory recall uses SQLite FTS5 full-text search with:

• BM25 ranking
• Recency bias (recent memories scored higher)
• Agent isolation (each agent’s memories are scoped by agent_id)

Retrieval is triggered at the start of every tick with the current market context as the query.

Self-Learning

After every tick with a trade outcome:

1. The harness captures the outcome (PnL, fill rate, slippage)
2. write_learning() formats a structured learning entry
3. Word-overlap deduplication filters near-duplicate learnings
4. Learning is appended to learnings/<date>.md
5. Next tick’s compose_bible() includes the learning in context

This is genuine self-improvement — agents get better at their specific strategy over time without fine-tuning.

CLI Access

# Read the full composed bible
koyal vault bible --agent trader1

# Read/write soul
koyal vault soul-read --agent trader1
koyal vault soul-write --agent trader1 --content "I trade conservatively..."

# Read/write instructions
koyal vault instructions-read --agent trader1
koyal vault instructions-write --agent trader1 --content "Rule 1: ..."

# List memories
koyal vault memories --agent trader1

# Take a snapshot (git-friendly)
koyal vault snapshot --agent trader1

API Access

# Get full bible
GET /api/vault/bible/{agent}

# Read/write soul
GET  /api/vault/soul/{agent}
PUT  /api/vault/soul/{agent}    {"content": "..."}

# Memories
GET  /api/vault/memories/{agent}
POST /api/vault/memories/{agent}  {"key": "...", "value": "...", "tags": [...]}

# Learnings
GET  /api/vault/learnings/{agent}
POST /api/vault/learnings/{agent}

# Propose an edit (goes through approval flow)
POST /api/vault/propose-edit/{agent}

Bot Scoping

Bots have their own config files inside the vault:

trading_agents/trader1/bots/
  bot1.md       ← bot1's strategy, risk config, loop links
  bot2.md       ← bot2's strategy

When a tick runs with bot_id = "bot1", compose_bible includes bots/bot1.md in the context, giving the AI full visibility into the bot’s specific rules on top of the agent’s soul and instructions.

Dashboard

The Vault page (/vault) in the web dashboard provides:

• Tree view of all vault files
• Inline editor for soul, instructions, and bot configs
• Memory browser with search
• Learnings timeline
• “Propose Edit” flow (edit goes through approval before writing to disk)