GitHub - memctl/memctl: Shared, persistent memory for AI coding agents. One project brain across machines and IDEs. Perfect for projects and teams.

4 min read Original article ↗

memctl logo

mem/ctl

Warning

This project is discontinued and the repository is archived.

Modern AI coding agents (Claude Code, Cursor, Codex, and others) now ship with built-in memory and context features that cover the same ground as mem/ctl. Using their native capabilities is the recommended path forward. This codebase remains available for reference only and will not receive further updates, bug fixes, or support.

Shared, persistent memory for AI coding agents.
One project brain across machines and IDEs.

Website · Docs · Changelog

npm version npm downloads CI License GitHub stars

What is mem/ctl?

mem/ctl is a cloud MCP server that gives AI coding agents shared, persistent memory scoped to projects and organizations. Claude Code, Cursor, Windsurf, Cline, Roo Code, Codex, OpenCode, and any MCP-compatible agent can read and write to the same project context.

Your team shares one brain. Every agent knows the architecture, conventions, decisions, and constraints without repeating yourself.

Quick start

npx memctl auth
npx memctl init

The init wizard detects your IDE and writes the MCP config automatically. Or configure manually:

{
  "mcpServers": {
    "memctl": {
      "command": "npx",
      "args": ["-y", "memctl@latest"],
      "env": {
        "MEMCTL_ORG": "<org-slug>",
        "MEMCTL_PROJECT": "<project-slug>"
      }
    }
  }
}

Agent support

Agent Config file Init shortcut Generate
Claude Code .mcp.json memctl init --claude memctl generate --claude
Cursor .cursor/mcp.json memctl init --cursor memctl generate --cursor
Windsurf ~/.codeium/windsurf/mcp_config.json memctl init --windsurf memctl generate --windsurf
Cline .vscode/mcp.json memctl init --cline memctl generate --cline
Roo Code .vscode/mcp.json memctl init --roo memctl generate --roo
Codex codex.json memctl init --codex memctl generate --codex
OpenCode opencode.json memctl init --opencode memctl generate --opencode

All agents, all at once:

MCP tools

mem/ctl exposes 11 tools to connected agents:

Tool What it does
memory Store, get, search, list, update, delete memories with dedup and tagging
memory_advanced Batch get, find similar, diff, merge, and rename keys
memory_lifecycle Archive, restore, history, bulk tag/untag, and capacity checks
context Bootstrap project context, delta sync, smart retrieval, rules evaluation
context_config Manage typed project guidance (coding style, architecture, constraints)
session Session lifecycle, conflict claims, and rate status
activity Memos, activity log, impact analysis
branch Branch-scoped context and implementation plans
repo Repository structure analysis
org Organization info and project listing
import_export Bulk import/export memories as JSON

Plus 7 resources and 3 prompts for richer agent integration.

How it works

  1. Agent connects to memctl via MCP (stdio transport)
  2. On startup, the agent bootstraps project context (conventions, architecture, constraints)
  3. During the session, the agent reads and writes memories as needed
  4. All agents on the team share the same project memory
  5. Session tracking prevents write conflicts across concurrent agents

Features

  • Project-scoped memory with key-value storage and rich metadata
  • Hybrid search combining FTS5 full-text and vector embeddings (all-MiniLM-L6-v2)
  • Smart deduplication that warns, skips, or merges similar content
  • Branch context for tracking implementation plans per git branch
  • Session management with conflict detection and automatic handoff
  • Activity memos for cross-session communication between agents
  • Content quality filter that blocks noise (shell dumps, raw diffs, JSON blobs)
  • Typed project guidance for architecture, coding style, folder maps, and constraints
  • Organization defaults that apply across all projects
  • Role-based access with owner, admin, and member roles
  • Self-hostable with Docker

Tech stack

Layer Technology
Runtime Node.js + TypeScript
Monorepo pnpm workspaces + Turborepo
Web Next.js 15 (App Router)
Database Turso (libSQL) + Drizzle ORM
Search FTS5 + vector embeddings
Auth better-auth (GitHub OAuth + magic link)
Payments Stripe
MCP @modelcontextprotocol/sdk
Testing Vitest

Project structure

apps/web/          Next.js dashboard + REST API
packages/cli/      MCP server + CLI (published to npm as "memctl")
packages/db/       Drizzle ORM schema + migrations
packages/shared/   Types, validators, constants

Development

git clone https://github.com/memctl/memctl.git
cd memctl
pnpm install
pnpm dev

See DOCKER.md for Docker-based development and CONTRIBUTING.md for contribution guidelines.

Useful commands

pnpm dev                     # Dev server (Turbopack)
pnpm lint                    # ESLint all packages
pnpm format:check            # Prettier check
npx vitest run               # Run tests
pnpm db:push                 # Push schema to DB
pnpm db:generate             # Generate migrations
pnpm db:migrate              # Run migrations

Self-hosting

Set SELF_HOSTED=true and NEXT_PUBLIC_SELF_HOSTED=true to run your own instance. This disables billing and unlocks all plan limits.

docker build --build-arg NEXT_PUBLIC_APP_URL=https://your-domain.com -t memctl-web .

See DOCKER.md for the full self-hosting guide.

Documentation

License

Apache-2.0