mem4agents

Persistent memory server for AI coding agents. Memories survive across sessions and context compactions.

Built on SQLite with FTS5 full-text search, exposed over MCP (Model Context Protocol) and HTTP.

Prerequisites

• Bun >= 1.0.0

curl -fsSL https://bun.sh/install | bash

Installation

# Install globally
bun add -g @alejandrocantero/mem4agents

# Or install locally in your project
bun add @alejandrocantero/mem4agents

Quick Start

1. Install and set up your agent

# Install globally
bun add -g @alejandrocantero/mem4agents

# Set up for Claude Code (plugin mode)
mem4agents setup claude-code

# Or set up for OpenCode
mem4agents setup opencode

The setup command prints the plugin directory path for Claude Code, or copies the plugin file for OpenCode.

• Claude Code — Native plugin with MCP server, hooks, skills, and commands (auto-discovered)
• OpenCode — Copies the plugin file and registers the MCP server

2. Start coding

That's it. Once set up, the memory system works automatically:

• Sessions are tracked on start and end
• Decisions, bug fixes, patterns, and discoveries are saved as memories
• Context is restored when starting a new session or after compaction
• User prompts are captured for future reference
• Passive learning extracts insights from subagent output

How It Works

mem4agents runs as an MCP server that your coding agent connects to. It provides 17 tools the agent uses to save, search, and manage memories stored in a local SQLite database.

┌─────────────┐     MCP (stdio)     ┌─────────────┐     SQLite     ┌──────────┐
│ Coding Agent│◄────────────────────►│  mem4agents  │◄─────────────►│  mem.db   │
│ (Claude, etc)│                     │  MCP Server  │   FTS5 search │          │
└─────────────┘                      └─────────────┘                └──────────┘
       │                                    │
       │          HTTP (port 7437)          │
       │  ┌──────────────────────────────┐  │
       └──┤  Hooks / Plugin scripts      ├──┘
          │  (session lifecycle, capture) │
          └──────────────────────────────┘

Memory types

| Type | When it's saved | |------|----------------| | decision | Architecture or design choice made | | bugfix | Bug fix completed | | discovery | Non-obvious finding about the codebase | | pattern | Convention or structure established | | config | Configuration or environment change | | preference | User preference or constraint learned | | architecture | System design documentation | | learning | General technical insight | | session_summary | End-of-session structured summary | | passive | Auto-extracted from subagent output | | general | Everything else |

Key features

• FTS5 full-text search with Porter stemming — "running" matches "run"
• Topic key upserts — evolving decisions update in place instead of creating duplicates
• Content deduplication — SHA-256 hash + 15-min rolling window
• Soft delete — memories are recoverable
• Privacy — <private>...</private> tags are stripped before any DB write
• Automatic context injection — recent memories and session history on startup

MCP Tools

Core (always loaded)

| Tool | Description | |------|-------------| | save_memory | Save a memory with project, title, content, type, and optional topic key for upserts | | search_memories | Full-text search with FTS5 + BM25 ranking, filtered by project/topic/type/scope | | mem_context | Get recent sessions, prompts, and memories — call at session start or after compaction | | session_summary | Save a structured end-of-session summary (Goal/Discoveries/Accomplished/Next Steps) |

Extended (loaded on demand)

| Tool | Description | |------|-------------| | get_memory | Get full untruncated content of a memory by ID | | update_memory | Update specific fields of an existing memory | | delete_memory | Soft-delete a memory (or hard-delete permanently) | | list_memories | List memories with filters, newest first | | list_projects | List all projects with memory counts | | list_topics | List topics within a project with counts | | session_start | Register the start of a coding session | | session_end | Mark a session as completed | | save_prompt | Save a user prompt for future context | | suggest_topic_key | Suggest a stable key for memory upserts | | capture_passive | Extract "Key Learnings" sections and save each as a memory | | mem_timeline | Get chronological context around a specific memory | | mem_stats | Get memory system statistics |

Running Manually

# MCP server (stdio transport) — used by agents directly
mem4agents

# HTTP API server — used by hooks and plugins
mem4agents serve          # default port 7437
mem4agents serve 8080     # custom port

# Check version and data paths
mem4agents --version

HTTP API

The HTTP server (mem4agents serve) exposes the same operations as the MCP tools, used by agent hooks and plugins for lifecycle management.

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | POST | /sessions | Create/register a session | | POST | /sessions/:id/end | End a session | | POST | /sessions/:id/summary | Save session summary | | POST | /save | Save a memory | | POST | /search | Full-text search | | GET | /context | Get recent context (query params: project, scope, limit) | | GET | /observation/:id | Get a memory by ID | | GET | /stats | Memory system statistics | | POST | /prompts | Save a user prompt | | POST | /observations/passive | Passive capture (extract Key Learnings) |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MEM4AGENTS_DB_PATH | <data_dir>/database/mem.db | Path to SQLite database file | | MEM4AGENTS_PORT | 7437 | HTTP API server port |

Data directory location (when installed as npm package):

• macOS: ~/Library/Application Support/mem4agents/
• Linux: $XDG_DATA_HOME/mem4agents/ (defaults to ~/.local/share/mem4agents/)

Project Structure

src/
  index.ts         — Entry point: subcommand routing (MCP, HTTP, setup)
  server.ts        — HTTP API server (Bun.serve)
  setup.ts         — Agent setup: plugin path printer (Claude Code) + installer (OpenCode)
  tools.ts         — 17 MCP tool definitions and handler dispatch
  types.ts         — TypeScript interfaces and config defaults
  lib/
    db.ts          — MemoryDB class: schema, CRUD, FTS5 search, sessions
    migrations.ts  — Schema versioning and migration runner
    logger.ts      — JSONL daily log file writer
plugin/
  claude-code/     — Claude Code plugin (hooks, skills, MCP config)
  opencode/        — OpenCode plugin adapter

Development

git clone https://github.com/streetclips/mem4agents.git
cd mem4agents
bun install

# Run in dev mode with hot reload
bun dev

# Run tests
bun test

# Lint
bun run lint
bun run lint:fix

License

MIT