How We Built memctl: Persistent Memory for AI Coding Agents

AI coding agents are powerful. They can write, refactor, debug, and ship code faster than anyone expected. But they have one glaring problem: amnesia.

Every time you start a new session, your agent forgets everything. Your architecture decisions, naming conventions, lessons from past bugs, project structure, all gone. You end up repeating yourself, pasting the same context, and watching your agent make the same mistakes you corrected yesterday.

We built memctl to fix that.

The Problem

Think about onboarding a new developer. You walk them through the codebase, explain the patterns, point out the gotchas. After a week, they get it. They stop asking the same questions.

Now think about your AI agent. Every session is day one. Every time, you re-explain that you use kebab-case filenames. That the API uses a specific middleware pipeline. That you tried approach X last week and it failed for reason Y.

This gets worse with teams. Developer A teaches their agent something useful. Developer B's agent has no idea. The knowledge stays locked in one session, on one machine, in one IDE.

What memctl Does

memctl is a cloud-based MCP server that gives AI agents persistent, shared memory scoped to your team and projects.

One command to set up:

npx memctl auth && npx memctl init

After that, your agent can store and retrieve memories across sessions, machines, and IDEs. When one team member's agent learns something, every other team member's agent picks it up on the next bootstrap.

11 Tools, 90+ Actions

We did not build a simple key-value store. memctl ships 11 MCP tools covering the full lifecycle of project knowledge:

• memory - Store, search, retrieve, pin, archive, and manage memories with priority scoring
• context - Bootstrap project context with delta sync, smart retrieval, and token budgeting
• session - Track agent sessions, detect conflicts when multiple agents work on the same project
• branch - Scope context and implementation plans to feature branches
• activity - Log what agents do, track impact, write session memos
• import/export - Bulk import from AGENTS.md, .cursorrules, or copilot-instructions.md

9 Built-in Context Types

Not all knowledge is the same. memctl organizes memories into typed categories:

• coding_style - Naming conventions, formatting rules, anti-patterns
• architecture - System design, module boundaries, data flow
• testing - Test frameworks, coverage requirements, patterns
• lessons_learned - Pitfalls, gotchas, things that failed before
• constraints - Hard requirements, security rules, performance limits
• workflow - Branching strategy, PR process, deployment steps
• folder_structure, file_map, branch_plan

You can also define custom context types for anything specific to your workflow.

Hybrid Search

Finding the right memory at the right time matters. memctl combines FTS5 full-text search with vector embeddings (all-MiniLM-L6-v2, 384 dimensions) using Reciprocal Rank Fusion. It scores results based on priority, usage frequency, recency, feedback, and pin status.

Your agent does not just dump everything into context. It retrieves what is actually relevant to the current task, within a configurable token budget.

Offline-First

The CLI maintains a local SQLite cache at ~/.memctl/cache.db. It does incremental delta syncs and queues writes when connectivity drops. When the connection comes back, pending writes replay automatically. ETag support means conditional requests return 304 when nothing changed. Your agent stays fast even with flaky networks.

The Dashboard

memctl is not just a CLI. The web dashboard gives you visibility into everything your agents are doing:

• Memory browser - View, search, edit, and organize all stored memories per project
• Activity feed - See what every agent stored, retrieved, updated, and deleted
• Health metrics - Track memory quality, find duplicates, identify stale entries
• Hygiene tools - Deduplicate, clean up, and maintain your memory pool
• Usage analytics - Monitor storage and API consumption
• Team management - Invite members, assign roles, control project access
• Token management - Generate and rotate API tokens

The interface is dense and terminal-like. Dark theme, monospace fonts, orange accent. No wasted space.

Works With Everything

memctl is an MCP server. That means it works with any MCP-compatible agent:

• Claude Code
• Cursor
• Windsurf
• Cline
• Roo Code
• Codex
• OpenCode
• Amazon Q
• JetBrains IDEs
• Continue
• Zed

One memory pool, accessible from any IDE, any machine, any team member.

Team-First Architecture

Organizations and projects are first-class concepts:

• Organizations hold members with roles (owner, admin, member)
• Projects scope memories to specific codebases
• Org-wide defaults automatically apply to every project
• Templates let you bootstrap new projects with pre-built memory sets
• Members see only their assigned projects. Admins see everything.

When someone on your team's agent figures out that a particular database query pattern causes N+1 problems, that knowledge propagates. The next agent session for any team member already knows.

Self-Hostable

We open-sourced memctl under Apache 2.0. You can self-host the entire stack with Docker:

docker compose up

Set SELF_HOSTED=true and all billing gates disappear. No Stripe, no payment walls, no limits. Run it on your own infrastructure, keep your data on your own servers.

The same Docker image that runs our cloud service runs self-hosted deployments.

What Changed for Us

We use memctl to build memctl. Here is what we noticed:

No more "remember that..." messages. Before memctl, every session started with pasting context. Now the agent bootstraps itself. It knows the codebase uses pnpm, that we never use default exports, that API responses follow { result?: T; error?: string }, and that we never run pnpm build unless explicitly asked.

Agents stop repeating mistakes. When an approach fails, it gets stored as a lesson learned. The next session already knows not to try it. This alone saves significant back-and-forth.

Onboarding agents to new projects is instant. Import an existing AGENTS.md or .cursorrules file, and the agent has a starting point. As it works, the memory grows organically.

Team knowledge compounds. Five developers working on the same project means five agents contributing to one memory pool. Patterns, conventions, and discoveries accumulate instead of evaporating.

Switching IDEs is seamless. Start a session in Cursor, continue in Claude Code, check something in Windsurf. The memory follows you.

The Tech Stack

For those curious about what powers memctl:

• Monorepo: pnpm workspaces + Turborepo
• Web: Next.js 15 with App Router and Turbopack
• Database: Turso (libSQL/SQLite) with Drizzle ORM, 28 tables
• Search: FTS5 + vector embeddings with Reciprocal Rank Fusion
• Auth: better-auth with GitHub OAuth, magic links, and dev bypass
• Payments: Stripe with six pricing tiers
• MCP: @modelcontextprotocol/sdk
• UI: shadcn/ui + Tailwind CSS, dark terminal aesthetic
• Testing: Vitest
• CI: GitHub Actions (lint, typecheck, test, build)

The CLI is a single npm package (memctl) that runs as both an MCP server and a standalone CLI. Zero config for MCP mode, full control in CLI mode.

Getting Started

  # Install and authenticate
  npx memctl auth

  # Set up your IDE
  npx memctl init

  # Check everything works
  npx memctl doctor

That is it. Three commands and your agent has persistent memory.

What is Next

We are actively building. The changelog tracks every release. The roadmap includes deeper IDE integrations, smarter retrieval algorithms, and more ways to organize and share project knowledge across teams.

AI agents are going to keep getting better. The missing piece was never intelligence. It was memory. memctl fills that gap.

---

memctl is open source under Apache 2.0. Self-host it or use the cloud version at memctl.com.