metazen11-tools

agent-memory

Persistent memory for AI coding agents that build, maintain, and enhance long-lived projects.

Most memory solutions assume your relationship with a project ends at git push. This one doesn't. If you maintain production systems, ship continuous improvements, and need your agent to remember why that Docker port was changed 4 months ago — agent-memory is built for you.

Records what was learned, built, fixed, and decided during each session, then makes it searchable via semantic + full-text hybrid search. Claude Code's built-in MEMORY.md gives you 200 lines of pinned notes. agent-memory gives you a searchable journal across thousands of observations — so accumulated context becomes a competitive advantage, not a truncated file.

Works with Claude Code out of the box. Designed to support any AI coding agent via REST API or MCP.

Quick Start

git clone https://github.com/metazen11/agent-memory.git
cd agent-memory
node install.js

The installer handles everything:

• Creates Python venv and installs dependencies
• Downloads embedding model (~400MB) and observation LLM (~1GB)
• Generates .env with random Postgres password
• Starts PostgreSQL (native Homebrew preferred, Docker fallback)
• Starts FastAPI server on port 3377
• Registers MCP server, hooks, and skills in Claude Code

Commands

node install.js              # Full setup + install
node install.js --status     # Show what's installed and running
node install.js --start      # Start services (Docker + FastAPI)
node install.js --stop       # Stop services
node install.js --migrate    # Run pending database migrations
node install.js --migrate --dry-run  # Preview migrations (no changes)
node install.js --migrate --backup   # Backup tables, then migrate
node install.js --backup     # Backup mem_* tables only
node install.js --uninstall  # Remove hooks, MCP, skills

Prerequisites

• PostgreSQL 16 + pgvector — macOS (recommended): brew install postgresql@16 pgvector | Docker fallback: brew install --cask docker | Linux: sudo apt install docker.io docker-compose-plugin
• Python 3.12+ — macOS: brew install [email protected] | Linux: sudo apt install python3.12 python3.12-venv
• Node.js — for the installer and hooks

Architecture

┌─────────────────────────────────────────────────────────┐
│  Claude Code Session                                    │
│                                                         │
│  session-start hook ──► Health check → auto-start       │
│                     └──► Inject MCP guide + context     │
│  post-tool-use hook ──► POST /api/queue (fire & forget) │
│  session-end hook   ──► PATCH /api/sessions/:id         │
└──────────────┬──────────────────────────────────────────┘
               │ HTTP (localhost:3377)
┌──────────────▼──────────────────────────────────────────┐
│  FastAPI Server (uvicorn, port 3377)                    │
│                                                         │
│  /api/queue ──► observation_queue table                  │
│  /api/observations ──► CRUD + hybrid search             │
│  /api/sessions ──► session lifecycle                     │
│  /api/admin ──► stats, re-embed                         │
│                                                         │
│  Queue Worker (background asyncio task)                 │
│  ├─ Dequeue pending items (FOR UPDATE SKIP LOCKED)      │
│  ├─ Generate observation via LLM (local GGUF → Haiku)   │
│  ├─ Embed via sentence-transformers (in-process)        │
│  └─ Insert into mem_observations with vector            │
└──────────────┬──────────────────────────────────────────┘
               │
┌──────────────▼──────────────────────────────────────────┐
│  MCP Server (stdio, separate process)                   │
│  Registered in ~/.claude/.mcp.json                      │
│                                                         │
│  Tools: search, timeline, get_observations, save_memory │
│  Own DB pool + embedding model (zero FastAPI deps)      │
└──────────────┬──────────────────────────────────────────┘
               │
┌──────────────▼──────────────────────────────────────────┐
│  PostgreSQL 16 + pgvector                               │
│  Native (Homebrew, launchd) or Docker container         │
│  Tables: mem_* prefixed (avoids collisions)             │
└─────────────────────────────────────────────────────────┘

How It Works

Recording (write path)

Every tool call in your coding session is captured:

1. PostToolUse hook fires (fire-and-forget, ~40ms)
2. Tool call data queued to /api/queue
3. Background worker dequeues with FOR UPDATE SKIP LOCKED
4. Local LLM extracts structured observation (title, type, narrative, facts)
5. Sentence-transformers generates 768-dim embedding
6. Inserted into PostgreSQL with pgvector index

Retrieval (read path)

Search past sessions via MCP tools (3-layer workflow):