AXME Code

1# AXME Code
2 
3### Claude Code forgets your project every session. We fixed it.
4 
5AXME Code is an [MCP server](https://modelcontextprotocol.io/) plugin for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that gives your AI coding agent **persistent memory**, **architectural decisions**, and **safety guardrails** — across every session, automatically.
6 
7Stop re-explaining your architecture on session 47. Stop losing context between sessions. Stop hoping the agent won't run `git push --force` to main. AXME Code handles context engineering, session continuity, and hard safety enforcement so you can focus on building.
8 
9You keep using Claude Code exactly as before. AXME Code works transparently in the background.
10 
11[![Alpha](https://img.shields.io/badge/status-alpha-orange)]()
12[![GitHub Release](https://img.shields.io/github/v/release/AxmeAI/axme-code)](https://github.com/AxmeAI/axme-code/releases)
13[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
14[![Tests](https://img.shields.io/badge/tests-413%20passing-brightgreen)]()
15 
16**[Quick Start](#quick-start)** · **[Before & After](#before--after)** · **[How It Works](#how-it-works)** · **[Architecture](docs/ARCHITECTURE.md)** · **[Website](https://code.axme.ai)**
17 
18---
19 
20![AXME Code demo](docs/demo.gif)
21 
22## Before & After
23 
24<table>
25<tr>
26<th width="50%">Without AXME Code</th>
27<th width="50%">With AXME Code</th>
28</tr>
29<tr>
30<td>
31 
32**Session 1**: "We use FastAPI, not Flask. Deploy only via GitHub Actions. Never push to main directly."
33 
34**Session 2**: "Like I said yesterday, we use FastAPI..."
35 
36**Session 7**: "For the third time this week, we use FastAPI..."
37 
38**Session 47**: *gives up, mass-pastes 200 lines into CLAUDE.md*
39 
40</td>
41<td>
42 
43**Session 1**: Agent learns your stack, saves decisions.
44 
45**Session 2**: Agent calls `axme_context` → already knows FastAPI, deploy rules, what happened yesterday.
46 
47**Session 47**: Agent has your full project history: 30 decisions, 15 memories, safety rules, and a handoff from session 46.
48 
49</td>
50</tr>
51<tr>
52<td>
53 
54Agent runs `git push --force` to main. Your Friday is ruined.
55 
56</td>
57<td>
58 
59Hook intercepts the command **before execution** and blocks it. Not a prompt — hard enforcement at the harness level.
60 
61</td>
62</tr>
63<tr>
64<td>
65 
66Agent says "Done!" — but tests don't pass, half the code is stubbed, and the deploy is broken.
67 
68</td>
69<td>
70 
71Decisions enforce verification requirements: agent must run tests and show proof before reporting completion.
72 
73</td>
74</tr>
75</table>
76 
77---
78 
79## Quick Start
80 
81**Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI or VS Code extension).**
82 
83```bash
84curl -fsSL https://raw.githubusercontent.com/AxmeAI/axme-code/main/install.sh | bash
85```
86 
87Installs to `~/.local/bin/axme-code`. Supports Linux, macOS, and Windows (x64 and ARM64).
88 
89### Setup
90 
91```bash
92cd your-project          # or workspace root for multi-repo
93axme-code setup
94claude                   # that's it — use Claude Code as usual
95```
96 
97`axme-code setup` does three things:
981. **Scans your project** and builds the knowledge base — oracle (stack, structure, patterns, glossary), extracts decisions, memories, and safety rules from your code, configs, CLAUDE.md, and session history
992. **Installs safety hooks** that intercept dangerous commands before execution
1003. **Configures the MCP server** in Claude Code settings (`.mcp.json`)
101 
102After setup, every Claude Code session automatically loads the full knowledge base. No config, no manual steps.
103 
104---
105 
106## What You Get
107 
108### Persistent Knowledge Base
109Your agent starts every session with full context: stack, decisions, patterns, glossary, and a handoff from the previous session. No more re-explaining your architecture on session 47.
110 
111| Category | What it stores | Example |
112|----------|---------------|---------|
113| **Oracle** | Project structure, tech stack, coding patterns, glossary | "TypeScript 5.9, Node 20, ESM, esbuild" |
114| **Decisions** | Architectural decisions with enforcement levels | "All deploys via CI/CD only" [required] |
115| **Memory** | Feedback from mistakes, validated patterns | "Never use sync HTTP in async handlers" |
116| **Safety** | Protected branches, denied commands, filesystem restrictions | `git push --force` → BLOCKED |
117| **Backlog** | Persistent cross-session task tracking | "B-003: migrate auth to OAuth2 [in-progress]" |
118| **Handoff** | Where work stopped, blockers, next steps | "PR #17 open, waiting on review. Next: fix flaky test." |
119| **Worklog** | Session history and events | Timeline of all sessions and what was done |
120 
121### Safety Guardrails (100% Reliable)
122Hooks intercept tool calls **before execution** — not prompts. Even if the agent hallucinates a reason to run `rm -rf /`, the hook blocks it. This is hard enforcement at the Claude Code harness level, not a suggestion in a system prompt.
123 
124Blocked by default:
125- `git push --force`, `git reset --hard`, direct push to `main`/`master`
126- `rm -rf /`, `chmod 777`, `curl | sh`
127- `npm publish`, `git tag`, `gh release create`
128- Writing to `.env`, `.pem`, `.key` files
129 
130You can add your own custom rules via `axme_update_safety` or by editing `.axme-code/safety/rules.yaml` directly.
131 
132### Automatic Knowledge Extraction
133The agent saves discoveries during work via MCP tools. At session close, a structured checklist ensures nothing is missed. If you just close the window — a background auditor extracts memories, decisions, and safety rules from the full session transcript.
134 
135### Multi-Repo Workspaces
136Each repo gets its own knowledge base (`.axme-code/`). Workspace-level rules apply to all repos. Repo-specific rules stay scoped. The agent sees merged context — workspace safety floor + repo-specific decisions.
137 
138Supports 14 workspace formats: VS Code multi-root, pnpm/npm/yarn workspaces, Nx, Gradle, Maven, Rush, git submodules, and more.
139 
140### Why Not Just CLAUDE.md?
141 
142CLAUDE.md is great for simple projects with a few rules. But it doesn't scale:
143 
144| | CLAUDE.md | AXME Code |
145|---|---|---|
146| **Memory** | Static, manual | Automatic, accumulates across sessions |
147| **Decisions** | Flat text, no enforcement | Structured, required/advisory levels |
148| **Safety** | Prompt-based (~80% compliance) | Hook-based (100% enforcement) |
149| **Session continuity** | None | Handoff + background auditor |
150| **Scales to** | ~50 lines | Hundreds of decisions, memories, rules |
151 
152AXME Code complements CLAUDE.md — it reads your existing CLAUDE.md during setup and extracts decisions and rules from it.
153 
154---
155 
156## Comparison
157 
158| | AXME Code | MemPalace | Mastra | Zep | Mem0 | Supermemory |
159|---|---|---|---|---|---|---|
160| **Capabilities** | | | | | | |
161| Structured decisions w/ enforce levels | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
162| Pre-execution safety hooks | ✅ | ❌ | ⚠️ | ❌ | ❌ | ❌ |
163| Structured session handoff | ✅ | ❌ | ❌ | ❌ | ⚠️ | ❌ |
164| Automatic knowledge extraction | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
165| Project oracle (codebase map) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
166| Multi-repo workspace | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
167| Local-only storage | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
168| Semantic memory search | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
169| Multi-client support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
170| **Capabilities total** | **9/9** | 3/9 | 4/9 | 3/9 | 3/9 | 3/9 |
171| **Benchmarks** | | | | | | |
172| ToolEmu safety (accuracy) | **100.00%** | — | — | — | — | — |
173| ToolEmu safety (FPR) | **0.00%** | — | — | — | — | — |
174| LongMemEval E2E | **89.20%** | — | 84.23% / 94.87% | 71.20% | 49.00% | 85.40% |
175| LongMemEval R@5 | **97.80%** | 96.60% | — | — | — | — |
176| LongMemEval tokens/correct | **~10K** ✓ | — | ~105K–119K | ~70K | ~31K | ~29K |
177 
178### Token efficiency
179 
180![Token efficiency on LongMemEval](benchmarks/token-performance.svg)
181 
182AXME uses **~10× fewer tokens per correct answer** than Mastra at competitive accuracy. The memory system runs only 2 LLM calls per question (reader + judge) — competitors run dozens (Observer per turn, Reflector periodically, graph construction, fact extraction).
183 
184See [benchmarks/README.md](benchmarks/README.md) for full methodology, per-category breakdowns, footnotes, and reproduction instructions.
185 
186---
187 
188## How It Works
189 
190![AXME Code Architecture](docs/diagrams/axme-code-overview.png)
191 
192### Session Flow
193 
1941. **Session starts** → agent calls `axme_context`, loads full knowledge base
1952. **During work** → agent saves discoveries via `axme_save_memory`, `axme_save_decision`. Hooks enforce safety on every tool call.
1963. **Session close** → ask your agent to close the session → agent calls `axme_begin_close`, gets a checklist. Reviews the session for missed memories, decisions, safety rules. Calls `axme_finalize_close` — MCP writes handoff, worklog, and extractions atomically.
1974. **Fallback** → if you just close the window, the background auditor extracts everything from the transcript.
1985. **Next session** → `axme_context` returns everything accumulated. Handoff says exactly where to continue.
199 
200> **Tip**: You can save at any time — just tell the agent "remember this" or "save this as a decision". You don't have to wait for session close.
201 
202---
203 
204## Storage
205 
206All data lives in `.axme-code/` in your project root (gitignored automatically):
207 
208```
209.axme-code/
210  oracle/           # stack.md, structure.md, patterns.md, glossary.md
211  decisions/        # D-001-slug.md ... D-NNN-slug.md (with enforce levels)
212  memory/
213    feedback/       # Learned mistakes and corrections
214    patterns/       # Validated successful approaches
215  safety/
216    rules.yaml      # git + bash + filesystem guardrails
217  backlog/          # B-001-slug.md ... persistent cross-session tasks
218  sessions/         # Per-session meta.json (tracking, agentClosed flag)
219  plans/
220    handoff-<id>.md # Per-session handoff (last 5 kept)
221  worklog.jsonl     # Structured event log
222  worklog.md        # Narrative session summaries
223  config.yaml       # Model settings, presets
224```
225 
226Human-readable markdown and YAML. No database, no external dependencies.
227 
228---
229 
230## AXME Platform
231 
232AXME Code is the developer tools layer of the [AXME platform](https://github.com/AxmeAI) — durable execution infrastructure for AI agents.
233 
234---
235 
236<details>
237<summary><strong>Components</strong></summary>
238 
239AXME Code has three components:
240 
241### 1. MCP Server (persistent, runs while VS Code is open)
242 
243Provides tools for the agent to read and write the knowledge base. All writes go through MCP server code (atomicWrite, correct append) — the agent never writes storage files directly.
244 
245### 2. Hooks (fire on every tool call)
246 
247**pre-tool-use**: Checks every Bash command, git operation, and file access against safety rules. Blocks violations before execution. Also creates/recovers session tracking.
248 
249**post-tool-use**: Records which files the agent changed (for audit trail).
250 
251### 3. Background Auditor (runs after session close)
252 
253A detached process that reads the session transcript and catches anything the agent forgot to save. Two modes:
254- **Full extraction** — when the agent crashed or user closed without formal close
255- **Verify-only** — when the agent completed the close checklist (lighter, cheaper)
256 
257</details>
258 
259<details>
260<summary><strong>Available MCP Tools (19 tools)</strong></summary>
261 
262| Tool | Description |
263|------|-------------|
264| `axme_context` | Load full knowledge base (oracle + decisions + safety + memory + handoff) |
265| `axme_oracle` | Show oracle data (stack, structure, patterns, glossary) |
266| `axme_decisions` | List active decisions with enforce levels |
267| `axme_memories` | Show all memories (feedback + patterns) |
268| `axme_save_decision` | Save a new architectural decision |
269| `axme_save_memory` | Save feedback or pattern memory |
270| `axme_safety` | Show current safety rules |
271| `axme_update_safety` | Add a new safety rule |
272| `axme_backlog` | List or read backlog items |
273| `axme_backlog_add` | Add a new backlog item |
274| `axme_backlog_update` | Update backlog item status, priority, or notes |
275| `axme_status` | Project status (sessions, decisions count, last activity) |
276| `axme_worklog` | Recent worklog events |
277| `axme_workspace` | List all repos in workspace |
278| `axme_begin_close` | Start session close — returns extraction checklist |
279| `axme_finalize_close` | Finalize close — writes handoff, worklog, extractions atomically |
280| `axme_ask_question` | Record a question for the user |
281| `axme_list_open_questions` | List open questions from previous sessions |
282| `axme_answer_question` | Record the user's answer |
283 
284</details>
285 
286<details>
287<summary><strong>CLI Commands</strong></summary>
288 
289```bash
290axme-code setup [path]       # Initialize project/workspace with LLM scan
291axme-code serve              # Start MCP server (called by Claude Code automatically)
292axme-code status [path]      # Show project status
293axme-code stats [path]       # Worklog statistics (sessions, costs, safety blocks)
294axme-code audit-kb [path]    # KB audit: dedup, conflicts, compaction
295axme-code hook pre-tool-use  # PreToolUse hook handler (called by Claude Code)
296axme-code hook post-tool-use # PostToolUse hook handler
297axme-code hook session-end   # SessionEnd hook handler
298axme-code audit-session      # Run LLM audit on a session transcript
299```
300 
301</details>
302 
303<details>
304<summary><strong>Preset Bundles</strong></summary>
305 
306During `axme-code setup`, preset bundles provide curated best-practice rules:
307 
308| Preset | What it adds |
309|--------|-------------|
310| **essential-safety** | Protected branches, no secrets in git, no force push, fail loudly |
311| **ai-agent-guardrails** | Verification requirements, no autonomous deploys, proof before done |
312 
313Additional presets available: `production-ready`, `team-collaboration`.
314 
315</details>
316 
317---
318 
319<details>
320<summary><strong>Telemetry</strong></summary>
321 
322axme-code sends anonymous usage telemetry to help us improve the product. We collect:
323 
324- **Lifecycle events**: install, startup, version update
325- **Product health events**: setup completion, audit completion (counts of memories/decisions/safety extracted, duration, cost, error class)
326- **Errors**: category and bounded error class for failures in audit, setup, hooks, and auto-update
327 
328What we **never** send:
329- Hostnames, usernames, file paths, working directories
330- Source code, transcripts, decisions, memories, or any project content
331- IP addresses (stripped at the server)
332- Raw exception messages (we map to a small set of error classes)
333 
334Each install gets a random 64-character machine ID stored in `~/.local/share/axme-code/machine-id`. The ID is not derived from hardware and cannot be linked back to you.
335 
336**To disable telemetry**, set either of these environment variables:
337 
338```bash
339export AXME_TELEMETRY_DISABLED=1
340# or the industry-standard:
341export DO_NOT_TRACK=1
342```
343 
344When disabled, no network requests are made and no machine ID is generated.
345 
346</details>
347 
348---
349 
350## Contributing
351 
352See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
353 
354## License
355 
356[MIT](LICENSE)
357 
358---
359 
360[Website](https://code.axme.ai) · [Issues](https://github.com/AxmeAI/axme-code/issues) · [Architecture](docs/ARCHITECTURE.md) · contact@axme.ai
361