agora-code

Persistent memory and context reduction for AI coding agents. Survives context window resets, new conversations, and agent restarts.

Install

Prerequisites: Python 3.10+ and pip. (Fully tested on macOS.)

Step 1 — Install the package (once, globally)

Open a terminal and run:

pip install git+https://github.com/thebnbrkr/agora-code.git

Verify:

agora-code --version

macOS permission error? (common on macOS system Python) Use --user instead:

pip install --user git+https://github.com/thebnbrkr/agora-code.git

Then add the binary to your PATH — add this line to ~/.zshrc or ~/.bashrc:

export PATH="$(python3 -m site --user-base)/bin:$PATH"

Step 2 — Set up a project

Run this in a terminal outside of Claude Code — Claude Code does not need to be open. (macOS: use Terminal.app.)

Claude Code:

cd your-project
agora-code install-hooks --claude-code

This creates:

• .claude/settings.json — registers all hooks with Claude Code
• .claude/hooks/*.sh — the hook scripts that fire automatically
• ~/.claude/skills/agora-code/SKILL.md — enables /agora-code globally (created once, works in all repos)
• .mcp.json — registers the memory MCP server

Already have .claude/settings.json? Use --force:

agora-code install-hooks --claude-code --force

Cursor:

Copy the .cursor/ directory from this repo into your project root:

cp -r /path/to/agora-code/.cursor your-project/.cursor

Or clone the repo and copy:

git clone https://github.com/thebnbrkr/agora-code.git /tmp/agora-code
cp -r /tmp/agora-code/.cursor your-project/.cursor

Gemini CLI:

Same approach — copy .gemini/ into your project root:

cp -r /tmp/agora-code/.gemini your-project/.gemini

Restart your editor after setup.

Step 3 — Start using it (Claude Code)

Open Claude Code in your project. At the start of every session, type:

/agora-code

This loads the skill — it tells Claude when to summarize files, when to inject context, and when to save progress. Without it, Claude doesn't know these rules exist.

Your previous session context is injected automatically on session start. To see what was loaded:

agora-code inject

What happens automatically

Cursor / Claude Desktop / other MCP editors

For editors without hook support, add to your MCP config:

{
  "mcpServers": {
    "agora-memory": {
      "command": "agora-code",
      "args": ["memory-server"]
    }
  }
}

Use which agora-code for the full path if your editor can't find it. Restart your editor.

Optional: better recall with embeddings

(This feature is actively being worked on — behaviour may change.)

By default recall uses FTS5 keyword search — works with no setup. For semantic (fuzzy) search:

export OPENAI_API_KEY=sk-...          # OpenAI text-embedding-3-small
export GEMINI_API_KEY=...             # Gemini gemini-embedding-001
pip install "git+https://github.com/thebnbrkr/agora-code[local]"  # offline, no API key

Two problems it solves

1. Token budget — large files eat your context fast

When an AI reads a 1000-line file it burns ~8000 tokens just for that read. agora-code intercepts every file read and serves a structured AST summary in

... View full README on GitHub