palace-ai

AI agents navigate code the way humans remember — by association, not search.

pip install palace-ai
palace build .
palace query "auth flow"
palace learn --task "..." --outcome success   # v2: record what worked

Build a traversable memory palace for any repository.
palace-ai turns a codebase into rooms and typed relationships so agents orient before opening raw files.

AST-only by default — no API key. Use --llm plus ANTHROPIC_API_KEY for richer room summaries.

What it does

Instead of dumping tens of thousands of tokens of source into context, an agent can read:

1. palace-out/PALACE.md — map of rooms
2. One room file — structure, exports, call hints
3. Only the source files it actually needs

On medium-to-large repos, navigation via the palace is often 10–42× smaller in tokens than reading the full tree (run palace stats after a build).

v2 — institutional memory: After tasks, run palace learn so the palace remembers patterns, failures, and codebase “game state.” New sessions read an enriched PALACE.md (what works, what to avoid, what’s incomplete). Use palace reflect periodically to re-derive patterns from the append-only attempt log.

Quick start

pip install palace-ai
palace build .
palace query "your topic"
palace serve                    # optional: graph visualizer
palace install claude           # Claude Code: CLAUDE.md + PreToolUse hook
palace learn --task "..." --outcome success --notes "..."   # v2 memory
palace reflect                  # v2: re-analyze all attempts
palace status                   # v2: game state summary

Explicit AST-only (same as default):

palace build . --no-llm

LLM-enriched rooms:

export ANTHROPIC_API_KEY=sk-...
palace build . --llm

Repo layout

2-minute demo

After clone — sample palace is at ./palace-out/:

pip install palace-ai
git clone https://github.com/RhyChaw/palace-ai.git && cd palace-ai
palace query "main" --threshold 0.05
palace serve

Larger graph — pre-built requests palace:

git clone https://github.com/RhyChaw/palace-ai.git && cd palace-ai
palace query "auth flow" --path examples/worked/requests
palace serve --path examples/worked/requests

License

MIT — see LICENSE.