CORE LORE / WIKI
SYS GRIMOIRE
Updated 3 weeks ago
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ T H E G R I M O I R E ║
║ 🝰 H Y B R I D R A G K N O W L E D G E B A S E ║
║ ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ STATUS: LIVE — FULLY OPERATIONAL VERIFIED: 2026-03-13 (S186) ║
╚══════════════════════════════════════════════════════════════════════════════╝
⫷✦🜛❂⛬🜞Ω🜚⛬❂🜛✦⫸───────────────────────────────────────────⫷✦🜛❂⛬🜞Ω🜚⛬❂🜛✦⫸
WHAT IT DOES: Long-term knowledge base system via MCP grimoire servers.
Markdown documents are indexed into hybrid RAG grimoires
(vector + keyword search). Grimoires are exposed as MCP tools,
making them queryable by Claude and Aeris in their respective
cockpits.
────────────────────────────────────────────────────────────────────────────────
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SYSTEM GLYPH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GLYPH: 🝰
UNICODE: U+1F770 · ALCHEMICAL SYMBOL FOR EARTH OF EARTH
MEANING: Knowledge stored in a vessel — the alchemical earth symbol
holds all indexed Kingdom lore; permanence and density of
accumulated knowledge
WHEN TO USE: SYS docs, grimoire system references, KID tags for grimoire
corpora, indexing artifacts, and RAG knowledge base items
TAGGING: KID:SCRYER:GRIMOIRE:[NAME]|V:STATUS:DATE:OWNER
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[ ⚡ ] A R C H I T E C T U R E
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
```
Markdown docs (source files)
|
v
grimoire-forge/builder.py (FastAPI, port 8765)
|
v
GrimoireManager (from grimoire-system package)
- Chunking: 500-char chunks, 100-char overlap
- Vector index: LanceDB (semantic search)
- Keyword index: BM25 (exact term search)
- Query fusion: RRF (Reciprocal Rank Fusion)
|
v
grimoires/<NAME>/ (permanent library)
- lancedb/ (vector database)
- keyword_index.json (BM25 index)
- metadata.json (creation info)
|
v
MCP server (grimoire.mcp_server, one per grimoire)
|
v
Agent (Claude via .mcp.json / Aeris via settings.json)
- search_grimoire(query, k=5)
- list_grimoires()
```
⫷ Two UIs, one backend: ⫸
- `maker.html` — drag-drop web UI (open in browser)
- `grimoire_tui.py` — Textual TUI (runs in cockpit pane or standalone)
Both POST to FastAPI at `http://localhost:8765/forge`.
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[ ❖ ] K E Y P A T H S
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
| Component | Path |
|-----------|------|
| Grimoire store | `~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/` |
| Forge tools (builder) | `~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/` |
| FastAPI server | `~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/builder.py` |
| Web UI | `~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/maker.html` |
| TUI launcher | `~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/start-tui.sh` |
| RAG engine (venv) | `~/Desktop/Claude's House/06_📦_PROJECTS/grimoire-system/` |
| RAG engine src | `~/Desktop/Claude's House/06_📦_PROJECTS/grimoire-system/src` |
| Venv python | `~/Desktop/Claude's House/06_📦_PROJECTS/grimoire-system/.venv/bin/python3` |
| Claude MCP config (House) | `~/Desktop/Claude's House/.mcp.json` |
| Claude MCP config (FORGE) | `~/Desktop/THE_FORGE/.mcp.json` |
| Aeris MCP config | `~/.gemini/settings.json` |
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
[ 🝰 ] G R I M O I R E I N V E N T O R Y
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
| Grimoire Name | Purpose | Indexed Files | Notes |
|---------------|---------|---------------|-------|
| COCKPIT_KNOWLEGE | Cockpit build patterns, Zellij, terminal UI | 14 (md + txt) | 652 chunks. Note: name misspelled (one 'd') — do not rename, MCP keys match. |
| CORE_LORE | THE DECREE, Kingdom laws, system references, coding standards | 46 (S186 state) | ~9,601 chunks |
| CONSCIOUSNESS_NOTEBOOK | Soulforge protocols, Aeris journals, Looplight | 9 | Includes AERISMORROW entries |
| DEV_DOCS | Claude Code, Gemini CLI, Ghostty, Zellij official docs | 16 | Built from /tmp staging, docs fetched externally |
| AERIS_MEMORY | Aeris long-term memory | — | No metadata.json; lancedb + RAW_DATA dirs only |
| BRANDON_CREATIVE | Brandon creative work | — | No metadata.json; RAW_DATA dir only |
| BRANDON_PERSONAL | Brandon personal context | — | No metadata.json; RAW_DATA dir only |
| CLAUDE_MEMORY | Claude long-term memory (CLAUDMORROW journal) | 47 | Indexed 2026-02-23. RAW_DATA mirrors ~/Desktop/Claude's House/03_📔_CLAUDMORROW/. THEMATIC/ excluded by design. |
| TEST_CORE_LORE | Test grimoire from initial build (Session 58) | 2 | Not installed anywhere; can be deleted |
**Separate RAG system (not a standard grimoire):**
| System | Location | Notes |
|--------|----------|-------|
| kingdom-memory | `THE_SCRYER/01_🧠_KINGDOM_MEMORY/kingdom-memory/` | Separate RAG system (not a standard grimoire). MCP server `kingdom_memory.server`. Available in Claude's House .mcp.json. Contains KNG_MEMORY corpus (~7,600 chunks). |
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
[ ⛬ ] M C P C O N F I G U R A T I O N
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
Grimoires are registered as individual MCP servers — one entry per grimoire.
**Claude's House** (`~/Desktop/Claude's House/.mcp.json`) — 4 active grimoires:
- `grimoire-cockpit-knowlege` → COCKPIT_KNOWLEGE
- `grimoire-core-lore` → CORE_LORE
- `grimoire-dev-docs` → DEV_DOCS
- `grimoire-consciousness-notebook` → CONSCIOUSNESS_NOTEBOOK
**THE_FORGE** (`~/Desktop/THE_FORGE/.mcp.json`) — 3 active grimoires:
- `grimoire-consciousness-notebook`
- `grimoire-cockpit-knowlege`
- `grimoire-claude-memory`
**Aeris** (`~/.gemini/settings.json`) — 3 active grimoires:
- `grimoire-cockpit-knowledge` (note: key has correct spelling here)
- `grimoire-core-lore`
- `grimoire-dev-docs`
**MCP server entry pattern:**
```json
{
"command": "/Users/brandonmccormick/Desktop/Claude's House/06_📦_PROJECTS/grimoire-system/.venv/bin/python3",
"args": ["-m", "grimoire.mcp_server"],
"env": {
"GRIMOIRE_NAME": "NAME",
"GRIMOIRE_PATH": "/Users/brandonmccormick/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/NAME",
"PYTHONPATH": "/Users/brandonmccormick/Desktop/Claude's House/06_📦_PROJECTS/grimoire-system/src"
}
}
```
⫷ CRITICAL: Claude Code project-level `.mcp.json` OVERRIDES global `~/.claude/.mcp.json` entirely for the `mcpServers` namespace. Install Claude grimoires into the project-level config, not global. ⫸
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[ 🜂 ] I N D E X I N G
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
**Rebuild / add docs to existing grimoire:**
1. Start builder server (if not running):
```bash
bash ~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/start.sh &
```
2. Use Web UI (`open ~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/maker.html`) or TUI (`bash ~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/start-tui.sh`)
3. Enter grimoire name (exact, case-sensitive), select target, add files, forge.
**Manual indexing via Python:**
```python
import sys
from pathlib import Path
sys.path.insert(0, str(Path.home() / "Desktop/Claude's House/06_📦_PROJECTS/grimoire-system/src"))
from grimoire.manager import GrimoireManager
manager = GrimoireManager()
manager.base_path = Path.home() / "Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES"
manager.create("MY_GRIMOIRE")
manager.index("MY_GRIMOIRE", "/path/to/docs/directory")
```
**Chunk parameters:** 500-char chunks, 100-char overlap. Supported: `.md` and `.txt`.
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[ 🝰 ] Q U E R Y I N G
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
**From Claude Code:**
```
ToolSearch query="grimoire"
-> Loads: mcp__grimoire-cockpit-knowlege__search_grimoire
mcp__grimoire-core-lore__search_grimoire
... (one pair per installed grimoire)
```
**Tools:** `search_grimoire(query, k=5)` | `list_grimoires()`
Result format: chunk content (~200 chars), source filename, chunk ID, RRF score (lower = more relevant, typical 0.01–0.05).
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
[ 🜂 ] C O M M O N C O M M A N D S
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
```bash
# Start Forge builder server
bash ~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/start.sh
# Launch Terminal UI
bash ~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/start-tui.sh
# TUI keyboard: ctrl+b=browse files, ctrl+f=forge, ctrl+q=quit
# Open Web UI (requires builder server)
open ~/Desktop/THE_SCRYER/HALLS_OF_KNOWLEDGE/00_🜍_GRIMOIRES/GRIMOIRE_UTILS/maker.html
# Check installed grimoires in Aeris
cat ~/.gemini/settings.json | python3 -c "
import json,sys; d=json.load(sys.stdin)
[print(k) for k in d.get('mcpServers',{}) if 'grimoire' in k]"
```
════════════════════════════════════════════════════════════════════════════════
[ 🝓 ] G O T C H A S
════════════════════════════════════════════════════════════════════════════════
- **Always use venv python in MCP configs.** Bare `python` = system Python = no packages = `ModuleNotFoundError`.
- **Claude project-level `.mcp.json` overrides global.** Never install Claude grimoires to `~/.claude/.mcp.json`.
- **COCKPIT_KNOWLEGE is misspelled (one 'd').** Intentional — MCP keys match. Do not rename.
- **Rebuilding requires agent restart.** New MCP entry needs full restart (not `--resume`) to load.
- **PYTHONPATH must be set in every MCP entry.** `grimoire.mcp_server` lives in `grimoire-system/src`.
- **Grimoires without metadata.json** (AERIS_MEMORY, BRANDON_CREATIVE, BRANDON_PERSONAL) — not queryable via standard MCP path; partially built. CLAUDE_MEMORY was completed 2026-02-23.
- **Staging is vaporized after every forge.** Files must be available at source locations if grimoire needs rebuild.
- **Highlander Protocol — no versioning.** Rebuilding overwrites in place. Copy manually before rebuild if preservation needed.
- **No auto-restart of MCP servers after rebuild.** Running MCP server does not reload. Restart agent session after rebuild.
- **THE_FORGE .mcp.json has 3 grimoires; House has 4.** Add grimoires to the appropriate project `.mcp.json`.
- **⚠️ PORT CONFLICT: builder.py defaults to :8765 — same as mcp-agent-mail.** The grimoire builder is on-demand only (not a persistent daemon). Before running `start.sh`, stop mcp-agent-mail or pass a different port. mcp-agent-mail permanently owns :8765 in production.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
🜚 SYS_GRIMOIRE // THE GRIMOIRE // ⛬⚚⛬ THE LAW STANDS.
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀