AXME Code

Claude Code forgets your project every session. We fixed it.

AXME Code is a Claude Code plugin that gives your AI coding agent persistent memory across sessions, pre-execution safety hooks, architectural decision enforcement, and structured session handoff — via an MCP server, automatically, across every session.

Stop re-explaining your architecture on session 47. Stop losing memory between session handoffs. Stop hoping the agent won't run git push --force to main. AXME Code remembers what happened, enforces your architectural decisions, continues where the last session stopped, and blocks dangerous commands before they execute — so you can focus on building.

You keep using Claude Code exactly as before. AXME Code works transparently in the background.

⭐ Star this repo if it saves you time · 🔔 Watch releases for new features · 💬 Discussions

Quick Start · Before & After · How It Works · Architecture · Website

Before & After

Quick Start

Requires Claude Code (CLI or VS Code extension).

Option 1: Claude Code plugin (recommended)

In Claude Code, run:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install axme-code@claude-community

Or from the terminal:

claude plugin marketplace add anthropics/claude-plugins-community
claude plugin install axme-code@claude-community

The plugin ships with the MCP server, safety hooks, and CLI bundled together; no separate binary to install. On first use in a project, just ask the agent to call axme_context — the plugin auto-initializes the knowledge base on that session.

Option 2: Standalone binary

Install the CLI system-wide (useful if you want to run axme-code outside Claude Code, e.g. for scripting).

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/AxmeAI/axme-code/main/install.sh | bash

Installs to ~/.local/bin/axme-code. Supports x64 and ARM64.

Windows (native):

irm https://raw.githubusercontent.com/AxmeAI/axme-code/main/install.ps1 | iex

Installs to %LOCALAPPDATA%\Programs\axme-code and adds it to your User PATH. Requires Node.js 20+ on PATH. Supports x64 and ARM64.

Windows via WSL2: if you already live in WSL2, use the Linux install one-liner inside your distro. Install Claude Code and axme-code inside the WSL distro, not on the Windows host.

Then in each project:

cd your-project          # or workspace root for multi-repo
axme-code setup
claude                   # that's it — use Claude Code as usual

axme-code setup does three things:

1. 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
2. Installs safety hooks that intercept dangerous commands before execution
3. Configures the MCP server in Claude Code settings (.mcp.json)

After setup, every Claude Code session automatically loads the full knowledge base. No config, no manual steps.

What You Get

Persistent Knowledge Base

Your 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.

Safety Guardrails (100% Reliable)

Hooks 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.

Blocked by default:

• git push --force, git reset --hard, direct push to main/master
• rm -rf /, chmod 777, curl | sh
• npm publish, git tag, gh release create
• Writing to .env, .pem, .key files

You can add your own custom rules via axme_update_safety or by editing .axme-code/safety/rules.yaml directly.

Automatic Knowledge Extraction

The 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.

Multi-Repo Workspaces

Each 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.

Supports 14 workspace formats: VS Code multi-root, pnpm/npm/yarn workspaces, Nx, Gradle, Maven, Rush, git submodules, and more.

Why Not Just CLAUDE.md?

CLAUDE.md is great for simple projects with a few rules. But it doesn't scale:

AXME Code complements CLAUDE.md — it reads your existing CLAUDE.md during setup and extracts decisions and rules from it.

Works With Any MCP Client

AXME Code is a stdio MCP server — every MCP-compatible AI coding assistant gets the full set of axme_* tools (knowledge base read/write, safety queries, status, worklog).

The MCP server entry is identical in every client:

{
  "mcpServers": {
    "axme": {
      "command": "axme-code",
      "args": ["serve"]
    }
  }
}

Just place it in your client's MCP config file:

• Cursor: ~/.cursor/mcp.json or .cursor/mcp.json (per-project)
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Cline: VS Code Settings → Cline MCP → cline_mcp_settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent

Pre-execution safety hooks, the post-tool-use file tracker, and the background session auditor are Claude Code-specific (they require Claude Code's hook system). In other clients, the agent must call AXME tools explicitly — same knowledge base, same .axme-code/ storage, just no automatic enforcement layer.

See docs/MULTI_CLIENT.md for full per-client setup, hook workarounds, and concurrent-client semantics.

Comparison

Token efficiency

AXME 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).

See benchmarks/README.md for full methodology, per-category breakdowns, footnotes, and reproduction instructions.

How It Works

Session Flow

1. Session starts → agent calls axme_context, loads full knowledge base
2. During work → agent saves discoveries via axme_save_memory, axme_save_decision. Hooks enforce safety on every tool call.
3. 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.
4. Fallback → if you just close the window, the background auditor extracts everything from the transcript.
5. Next session → axme_context returns everything accumulated. Handoff says exactly where to continue.

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.

Storage

All data lives in .axme-code/ in your project root (gitignored automatically):

.axme-code/
  oracle/           # stack.md, structure.md, patterns.md, glossary.md
  decisions/        # D-001-slug.md ... D-NNN-slug.md (with enforce levels)
  memory/
    feedback/       # Learned mistakes and corrections
    patterns/       # Validated successful approaches
  safety/
    rules.yaml      # git + bash + filesystem guardrails
  backlog/          # B-001-slug.md ... persistent cross-session tasks
  sessions/         # Per-session meta.json (tracking, agentClosed flag)
  plans/
    handoff-<id>.md # Per-session handoff (last 5 kept)
  worklog.jsonl     # Structured event log
  worklog.md        # Narrative session summaries
  config.yaml       # Model settings, presets

Human-readable markdown and YAML. No database, no external dependencies.

AXME Platform

AXME Code is the developer tools layer of the AXME platform — durable execution infrastructure for AI agents.

axme-code setup [path]       # Initialize project/workspace with LLM scan
axme-code serve              # Start MCP server (called by Claude Code automatically)
axme-code status [path]      # Show project status
axme-code stats [path]       # Worklog statistics (sessions, costs, safety blocks)
axme-code audit-kb [path]    # KB audit: dedup, conflicts, compaction
axme-code hook pre-tool-use  # PreToolUse hook handler (called by Claude Code)
axme-code hook post-tool-use # PostToolUse hook handler
axme-code hook session-end   # SessionEnd hook handler
axme-code audit-session      # Run LLM audit on a session transcript

export AXME_TELEMETRY_DISABLED=1
# or the industry-standard:
export DO_NOT_TRACK=1

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT

Website · Issues · Architecture · [email protected]