{
  "markdown": "# agent-memory\n\n**Save 60-90% on LLM token costs** with intelligent memory compression for multi-agent systems.\n\nagent-memory compresses raw LLM tool output into structured observations, shares context across agents via a memory bus, and injects only relevant memory into each prompt — keeping your token budget under control.\n\n---\n\n## The Problem\n\nRunning 5+ concurrent LLM agents burns tokens fast:\n- Each agent re-reads the same files, re-discovers the same context\n- Raw tool output (file reads, command results) consumes thousands of tokens\n- No shared memory means redundant API calls across agents\n- You hit rate limits and token budgets within minutes\n\n## The Solution\n\nagent-memory sits between your agents and their context window:\n\n```\nRaw Tool Output (5,000 tokens)\n  -> Observation Compression (500 tokens)\n    -> Shared Memory Bus (SQLite + FTS5)\n      -> Budget-Controlled Context Injection (8,000 token cap)\n```\n\n**Tested results**: 66-94% token savings, 3-74x compression ratio.\n\n---\n\n## Quick Start\n\n### As a Python SDK\n\n```bash\npip install agent-memory\n```\n\n```python\nfrom agent_memory import MemoryStore, ContextBuilder\n\n# Initialize\nmemory = MemoryStore(\"./my_project.db\")\n\n# Store a compressed observation\nmemory.store_observation(Observation(\n    agent_id=\"researcher-1\",\n    project=\"my-app\",\n    title=\"Found pagination bug in /users endpoint\",\n    narrative=\"The API returns 500 when page > 100 due to missing LIMIT clause\",\n    facts=[\"Max page size is 100\", \"No server-side validation\"],\n    concepts=[\"api\", \"bug\", \"pagination\"],\n))\n\n# Build context for another agent (token-budgeted)\nbuilder = ContextBuilder(memory)\ncontext = builder.build(\n    project=\"my-app\",\n    agent_id=\"coder-1\",\n    task_description=\"Fix the pagination bug\",\n)\n# -> Returns compressed context within 8000 token budget\n# -> Includes researcher-1's findings automatically\n```\n\n### As a Claude Code Plugin\n\n#### Step 1: Install\n\n```bash\n# Add the marketplace\nclaude plugin marketplace add Keshab0310/agent-memory\n\n# Install the plugin\nclaude plugin install agent-memory@keshab-plugins\n```\n\nVerify it's installed:\n```bash\nclaude plugin list\n# Should show: agent-memory@keshab-plugins  v0.1.0  ✔ enabled\n```\n\n#### Step 2: Use It (It's Automatic)\n\nOnce installed, the plugin works **silently in the background** with zero configuration:\n\n**What happens automatically:**\n- Every time Claude reads a file, runs a command, or edits code, the **PostToolUse hook** compresses that tool output into a structured observation and stores it locally\n- Every time you start a new session (or resume one), the **SessionStart hook** injects relevant past observations into Claude's context\n- Your plan is auto-detected (Pro/Max/API) and memory budgets adjust accordingly\n\n**You don't need to change how you use Claude Code.** Just work normally — the plugin handles compression and recall behind the scenes.\n\n#### Step 3: Search Past Work (MCP Tools)\n\nThe plugin exposes 4 MCP tools that Claude can use when you ask about past work:\n\n```\nYou: \"What did we find about the database schema yesterday?\"\nClaude: [uses memory_search tool] -> finds relevant observations\n  -> \"Yesterday we discovered the users table was missing an index\n     on email, which caused the slow login query. We added a B-tree\n     index and response time dropped from 2.3s to 45ms.\"\n```\n\n```\nYou: \"How much have we saved on tokens?\"\nClaude: [uses memory_stats tool]\n  -> \"156 observations stored. Compression ratio: 18.2:1.\n     Token savings: 94%. Estimated cost saved: $1.34.\"\n```\n\nThe 4 tools available:\n| Tool | What It Does | When Claude Uses It |\n|------|-------------|-------------------|\n| `memory_search` | Searches past observations by keyword/topic | When you ask \"what did we find about X?\" |\n| `memory_store` | Manually stores an observation | When you say \"remember this for later\" |\n| `memory_stats` | Shows token savings dashboard | When you ask about costs or savings |\n| `memory_context` | Builds a context summary for a task | When starting complex multi-step work |\n\n#### Step 4: Check It's Working\n\nAfter using Claude Code for a few tasks with the plugin installed:\n\n```\nYou: \"Show me my memory stats\"\nClaude: [uses memory_stats]\n  Total observations: 23\n  Compression ratio: 12.4:1\n  Token savings: 91%\n```\n\nIf you see observations being stored and savings > 0%, the plugin is working.\n\n#### Uninstall\n\n```bash\nclaude plugin uninstall agent-memory@keshab-plugins\nclaude plugin marketplace remove keshab-plugins\n```\n\n#### Plugin Data Location\n\nAll data is stored locally:\n- **SQLite database**: `~/.claude/plugins/data/agent-memory/memory.db`\n- **No data leaves your machine** — see [PRIVACY.md](./PRIVACY.md)\n\nDelete all plugin data:\n```bash\nrm -rf ~/.claude/plugins/data/agent-memory/\n```\n\n---\n\n### With Local LLMs (Ollama, LM Studio)\n\n```python\nfrom agent_memory import LocalLLMAgent, AgentConfig, MemoryStore\n\nmemory = MemoryStore(\"./local.db\")\nagent = LocalLLMAgent(\n    config=AgentConfig(agent_type=\"researcher\", model=\"phi4:latest\"),\n    memory=memory,\n    project=\"my-app\",\n    base_url=\"http://localhost:11434/v1\",  # Ollama\n)\nresult = agent.execute(\"What are the key design patterns in this codebase?\")\n```\n\n---\n\n## How It Works\n\n### 1. Observation Compression\n\nRaw tool output (file reads, command results, API responses) gets compressed into structured observations:\n\n```\n[discovery] Found pagination bug in /users endpoint\n  API returns 500 when page > 100 due to missing LIMIT clause\n  - Max page size is 100\n  - No server-side validation\n```\n\nA 5,000-token file read becomes a 200-token observation. That's a **25x compression ratio**.\n\n### 2. Shared Memory Bus\n\nAll agents write to and read from a shared memory store:\n\n```\nSQLite (structured queries) + FTS5 (full-text search)\n  |\n  +-- Optional: ChromaDB (semantic vector search)\n```\n\nAgent B sees what Agent A discovered — no re-querying needed.\n\n### 3. Token-Budgeted Context Injection\n\nBefore each agent call, the ContextBuilder assembles a minimal context window:\n\nBudget adapts to your plan automatically:\n\n| Plan | Total Budget | Own Obs | Cross-Agent | Why |\n|------|-------------|---------|-------------|-----|\n| **Pro + Sonnet** | 8,000 | 4,000 | 2,400 | Capped usage — stay lean |\n| **Pro + Opus** | 5,000 | 2,500 | 1,500 | Opus burns limits fast — ultra-lean |\n| **Max + Sonnet** | 16,000 | 8,000 | 5,000 | Unlimited — go wider |\n| **Max + Opus** | 50,000 | 25,000 | 18,000 | Unlimited + 1M window — go deep |\n| **Local LLM** | 1,500 | 700 | 300 | Small context windows |\n\n### 4. Prompt Caching (Anthropic)\n\nStatic content gets cache breakpoints for 90% input cost reduction:\n\n```\nSystem prompt     [CACHED - 10% cost]\nShared context    [CACHED - 10% cost]\nAgent memory      [dynamic - full cost]\nUser message      [dynamic - full cost]\n```\n\n---\n\n## Real-World Use Cases\n\n### Use Case 1: Multi-File Refactoring Without Context Loss\n\n**The problem:** You ask Claude Code to refactor authentication across 15 files. By file 8, it's forgotten the patterns established in files 1-3. It re-reads them, burning tokens. By file 12, you hit context limits.\n\n**How agent-memory solves it:**\n```\nFile 1-3: Claude reads and refactors auth code\n  -> PostToolUse hook compresses each file read into an observation:\n     [change] Refactored auth.py — replaced session tokens with JWT\n     - New pattern: verify_jwt() middleware on all protected routes\n     - Removed: legacy session_store dependency\n     \nFile 4-15: Claude continues refactoring\n  -> SessionStart hook injects compressed observations from files 1-3\n  -> Claude sees the patterns (150 tokens) instead of re-reading files (5,000 tokens)\n  -> 97% token savings on context recall\n```\n\n**Before agent-memory:** 15 files x 5,000 tokens each = 75,000 tokens re-read\n**After agent-memory:** 15 observations x 150 tokens = 2,250 tokens. **97% savings.**\n\n---\n\n### Use Case 2: Debugging Across Sessions\n\n**The problem:** Yesterday you spent 2 hours debugging a race condition. You found the root cause, tried 3 approaches, and fixed it. Today, a related bug appears. Claude Code has zero memory of yesterday's work. You start from scratch.\n\n**How agent-memory solves it:**\n```\nYesterday's session (auto-captured by hooks):\n  [discovery] Race condition in WebSocket handler\n    - write_lock missing on shared_state dict\n    - Reproduced with 5+ concurrent connections\n    - Tried: asyncio.Lock (failed — wrong event loop)\n    - Tried: threading.Lock (worked but caused deadlock in tests)\n    - Fixed: threading.RLock with 5s timeout\n\nToday's session:\n  You: \"There's another threading issue in the notification service\"\n  -> SessionStart hook injects yesterday's context automatically\n  -> Claude sees the RLock pattern that worked\n  -> Skips the 2 failed approaches\n  -> Applies the proven fix in one shot\n```\n\n**Without agent-memory:** 45 minutes re-investigating the same threading patterns\n**With agent-memory:** 5 minutes — Claude already knows what works in your codebase\n\n---\n\n### Use Case 3: Multi-Agent Research Pipeline\n\n**The problem:** You spawn 5 agents to research, code, review, test, and document a feature. Each agent works in isolation. The coder doesn't know what the researcher found. The reviewer doesn't know what the coder tried and rejected.\n\n**How agent-memory solves it:**\n```python\nfrom src.profiles import detect_profile\nfrom src.agents.base import Agent\nfrom src.agents.registry import get_agent_config\nfrom src.memory.store import MemoryStore\n\nmemory = MemoryStore(\"./shared.db\")\n\n# Agent 1: Researcher finds the best approach\nresearcher = Agent(get_agent_config(\"researcher\"), memory, \"my-project\")\nresearcher.execute(\"Research OAuth2 vs API keys for our B2B API\")\n# -> Stores: [discovery] OAuth2 better for B2B — supports scopes, token rotation\n\n# Agent 2: Coder sees the researcher's findings automatically\ncoder = Agent(get_agent_config(\"coder\"), memory, \"my-project\")\ncoder.execute(\"Implement the auth system\")\n# -> ContextBuilder injects: \"Researcher found OAuth2 is better for B2B...\"\n# -> Coder builds OAuth2 without asking \"which auth method?\"\n\n# Agent 3: Reviewer sees BOTH researcher reasoning AND coder implementation\nreviewer = Agent(get_agent_config(\"reviewer\"), memory, \"my-project\")\nreviewer.execute(\"Review the auth implementation\")\n# -> Sees researcher's OAuth2 rationale + coder's implementation decisions\n# -> Reviews against the original requirements, not just code syntax\n```\n\n**Without shared memory:** Reviewer says \"why not API keys?\" — coder explains — wastes 2 round trips\n**With shared memory:** Reviewer already has context. Zero redundant conversation.\n\n---\n\n### Use Case 4: Pro Plan Token Budget Optimization\n\n**The problem:** You're on the Pro Plan using Opus 4.6. Adaptive thinking on \"High\" burns through your daily limit in 10 messages. Each message costs ~$0.50+ in tokens because the context window fills with raw tool output.\n\n**How agent-memory solves it:**\n```\nWithout agent-memory (Opus on Pro):\n  Message 1: Read 3 files (15,000 tokens) + Opus thinking (25,000 tokens) = 40,000 tokens\n  Message 2: Re-reads same files + new query = 45,000 tokens  \n  Message 3: Context growing, Opus thinking harder = 60,000 tokens\n  Total after 3 messages: 145,000 tokens. Daily limit: approaching fast.\n\nWith agent-memory (auto-detects opus-pro profile):\n  Message 1: Read 3 files -> compressed to 3 observations (450 tokens)\n             Opus thinking capped at 10,000 tokens = 25,000 total\n  Message 2: Observations injected (450 tokens, not 15,000)\n             New query + thinking = 18,000 total\n  Message 3: 5,000 token memory budget, lean injection = 20,000 total\n  Total after 3 messages: 63,000 tokens. 57% savings.\n```\n\nThe plugin auto-detects your plan:\n```python\n# No configuration needed — it reads your environment\nfrom src.profiles import detect_profile\n\nprofile = detect_profile()  # Returns opus-pro automatically\n# -> 5,000 token memory budget (not 50,000)\n# -> Thinking capped at 10,000 tokens\n# -> Aggressive condensation every 3 observations\n# -> Your Pro Plan lasts 3x longer\n```\n\n---\n\n### Use Case 5: Onboarding to a New Codebase\n\n**The problem:** You join a new team and need to understand a 500-file codebase. You ask Claude Code to explore it. After reading 20 files, the context is full of raw file contents, and Claude can't synthesize what it learned.\n\n**How agent-memory solves it:**\n```\nSession 1: \"Help me understand this codebase\"\n  Claude reads package.json, README, key source files\n  -> Each file read compressed into observations:\n     [discovery] FastAPI backend with SQLAlchemy ORM\n       - 3-layer architecture: routers/ -> services/ -> models/\n       - PostgreSQL with Alembic migrations\n     [discovery] React frontend with Redux state\n       - Component library in src/ui/\n       - API calls centralized in src/api/client.ts\n     [discovery] Auth uses JWT with refresh tokens\n       - Tokens stored in httpOnly cookies\n       - 15-min access token, 7-day refresh\n\nSession 2 (next day): \"Add a new API endpoint for user preferences\"\n  -> SessionStart hook injects Session 1 observations\n  -> Claude already knows: FastAPI + SQLAlchemy + JWT auth + 3-layer pattern\n  -> Immediately creates: models/preferences.py, services/preferences.py,\n     routers/preferences.py following the existing pattern\n  -> No re-exploration needed\n```\n\n**Without agent-memory:** Re-read 10+ files every session to rebuild context\n**With agent-memory:** Instant recall of codebase architecture in ~2,000 tokens\n\n---\n\n### Use Case 6: Cost Monitoring Dashboard\n\n**The problem:** You have no visibility into how many tokens your agents consume. You can't tell which agent is wasteful or whether your optimizations are working.\n\n**How agent-memory solves it:**\n```python\nfrom src.metrics.tracker import MetricsTracker\nfrom src.memory.store import MemoryStore\n\nmemory = MemoryStore(\"./data/memory.db\")\ntracker = MetricsTracker(memory)\ntracker.print_dashboard(\"my-project\")\n```\n\nOutput:\n```\n============================================================\nMULTI-AGENT SYSTEM METRICS\n============================================================\nTotal API calls:      47\nTotal tokens:         284,000\nCached tokens:        89,000\nCache hit rate:       31.3%\nCompression ratio:    18.2:1\nToken savings:        94%\nObservations stored:  156\nAvg latency:          3,200ms\n\nPer-Agent Breakdown:\n------------------------------------------------------------\nType            Calls    Cache%   Cost Ratio   Latency\ncoder           15       38.2%   0.68x       4,100ms\nresearcher      12       29.1%   0.74x       2,800ms\nreviewer        10       33.5%   0.71x       2,400ms\nplanner          5       18.7%   0.85x       3,900ms\nsummarizer       5       44.2%   0.62x       1,200ms\n============================================================\n```\n\nOr use the MCP tool directly in Claude Code:\n```\nYou: \"How much have we saved on tokens?\"\nClaude: Uses memory_stats tool\n  -> \"156 observations, 18.2:1 compression ratio, 94% token savings.\n      Estimated savings: ~267,000 tokens ($1.34 at Sonnet pricing).\"\n```\n\n---\n\n### Use Case 7: Local LLM Development (Zero API Cost)\n\n**The problem:** You want to develop and test multi-agent workflows but don't want to burn API credits during prototyping.\n\n**How agent-memory solves it:**\n```bash\n# Start Ollama\nollama serve\n\n# Run the full 3-agent pipeline locally\npython run_local.py --model phi4:latest\n```\n\n```\nAGENT: RESEARCHER\n  Task: Research token optimization strategies...\n  Generating... done (114.3s)\n  Observations: 1 [discovery] Three Core Optimization Strategies\n\nAGENT: CODER  \n  Task: Implement context builder...\n  Context injected: researcher's findings (automatic)\n  Generating... done (154.0s)\n  Observations: 1 [feature] build_context Function\n\nAGENT: REVIEWER\n  Task: Review the implementation...\n  Context injected: researcher + coder findings (automatic)\n  Generating... done (90.2s)\n  Observations: 1 [discovery] Greedy Algorithm Review\n\nToken Economics:\n  Compression: 3.0:1\n  Savings: 66%\n  Cost: $0.00\n```\n\nThe entire memory pipeline (compression, shared memory, context injection) works identically with local models. When you're ready, switch to Anthropic with zero code changes:\n```python\n# Local development\nagent = LocalLLMAgent(config, memory, project, base_url=\"http://localhost:11434/v1\")\n\n# Production — just swap the class\nagent = Agent(config, memory, project)  # Uses Anthropic API\n```\n\n---\n\n### Use Case 8: Plugin Auto-Adapts to Your Plan\n\n**The problem:** You shouldn't have to configure anything. The plugin should just work optimally whether you're on Pro, Max, or using a local LLM.\n\n**How agent-memory solves it:**\n\nThe plugin auto-detects your model and plan at startup:\n\n| Your Setup | Auto-Detected Profile | Memory Budget | Thinking Cap |\n|------------|----------------------|---------------|-------------|\n| Pro + Sonnet (default) | `sonnet-pro` | 8,000 tokens | none |\n| Pro + Opus (/extra-usage) | `opus-pro` | 5,000 tokens | 10,000 |\n| Max + Sonnet | `sonnet-max` | 16,000 tokens | none |\n| Max + Opus | `opus-max` | 50,000 tokens | none |\n| API key (direct) | `sonnet-api` | 8,000 tokens | none |\n| Ollama / LM Studio | `local` | 1,500 tokens | none |\n\nNo configuration files. No environment variables to set. It reads `CLAUDE_MODEL`, `CLAUDE_CODE_MAX_PLAN`, and `ANTHROPIC_API_KEY` from your environment and picks the optimal profile.\n\nOverride if needed:\n```bash\n# Force Max Plan profile (if auto-detection gets it wrong)\nexport AGENT_MEMORY_PLAN=max\n```\n\n---\n\n## Architecture\n\n```\nsrc/\n  memory/\n    store.py            # SQLite + ChromaDB + FTS5 memory layer\n    context_builder.py  # Token-budgeted context injection\n    condenser.py        # Periodic summarization pipeline\n  agents/\n    base.py             # Base agent with memory integration\n    local_llm.py        # Ollama/LM Studio adapter\n    registry.py         # Agent type definitions\n  cache/\n    prompt_cache.py     # Anthropic prompt caching wrapper\n    rate_limiter.py     # Token bucket RPM/TPM limiter\n  orchestrator/\n    router.py           # DAG-based multi-agent task router\n  metrics/\n    tracker.py          # Token/cache/latency tracking\nplugin/\n  mcp_server.py         # MCP server for Claude Code\n  hooks/\n    post_tool_use.py    # Auto-compress tool output\n    session_start.py    # Inject memory at session start\n  plugin.json           # Claude Code plugin manifest\ntests/\n  test_memory.py        # Memory store + search + condensation tests\n  test_orchestrator.py  # DAG execution + cache structure tests\n```\n\n---\n\n## Key Features\n\n| Feature | Status |\n|---------|--------|\n| Observation compression (XML/auto-extract) | Working |\n| SQLite + FTS5 search | Working |\n| ChromaDB semantic search (optional) | Working |\n| Token-budgeted context injection | Working |\n| Anthropic prompt caching | Working |\n| Rate limiter (RPM + TPM) | Working |\n| Periodic condensation | Working |\n| Local LLM support (Ollama/LM Studio) | Working |\n| Multi-agent shared memory | Working |\n| DAG-based orchestrator | Working |\n| Metrics dashboard | Working |\n| Claude Code plugin (MCP + hooks) | Beta |\n\n---\n\n## Running the Demos\n\n### Dry-run validation (no API key needed)\n\n```bash\npython run_demo.py\n```\n\n### Live with Anthropic API\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\npython run_demo.py --live\n```\n\n### Local LLM (Ollama)\n\n```bash\nollama serve  # In another terminal\npython run_local.py --model phi4:latest\n```\n\n---\n\n## Testing\n\n```bash\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\nAll 14 tests cover: memory CRUD, agent isolation, condensation, semantic search, token budgets, cache breakpoints, DAG execution, and metrics logging.\n\n---\n\n## Configuration\n\n### Memory Budget\n\n```python\nfrom agent_memory import ContextBudget\n\nbudget = ContextBudget(\n    total=8000,           # Total token budget for context\n    task_description=800, # Reserved for task text\n    own_observations=4000,# Agent's own recent work\n    cross_agent=2400,     # Other agents' relevant findings\n    summaries=800,        # Condensed history\n)\n```\n\n### Rate Limiting\n\n```python\nfrom agent_memory.cache import RateLimiter\n\nlimiter = RateLimiter(\n    requests_per_minute=50,\n    tokens_per_minute=80_000,\n)\nlimiter.acquire_sync(estimated_tokens=4000)  # Blocks until slot available\n```\n\n### Agent Types\n\nBuilt-in: `researcher`, `coder`, `reviewer`, `summarizer`, `planner`. Custom:\n\n```python\nconfig = AgentConfig(\n    agent_type=\"my-agent\",\n    model=\"claude-sonnet-4-6-20250514\",\n    max_output_tokens=2000,\n    system_prompt=\"You are a specialized agent for...\",\n)\n```\n\n---\n\n## Benchmarks\n\nMeasured on real workloads (not synthetic):\n\n| Metric | Result |\n|--------|--------|\n| Token savings (compression) | 66-94% |\n| Compression ratio | 3:1 to 74:1 |\n| Prompt cache hit rate | 23-35% |\n| Cache cost reduction | 0.71x |\n| Context budget utilization | 43% avg |\n| Cross-agent memory sharing | 100% (all agents see shared pool) |\n\n---\n\n## API Reference\n\nSee [API_REFERENCE.md](./API_REFERENCE.md) for the complete SDK documentation.\n\n---\n\n## Contributing\n\n1. Fork the repo\n2. Create a feature branch\n3. Run tests: `pytest tests/ -v`\n4. Submit a PR\n\n---\n\n## License\n\nMIT - see [LICENSE](./LICENSE)\n",
  "bytes": 21200,
  "sha": "097ff0633384e7e8f004c316387fcf41a058c988f3472b04ef3804cd4e6dffd4",
  "repo_slug": "keshab0310/agent-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_keshab0310_agent_memory_agent_memory_2a8f0ccc/readme"
}