Open-source agent memory

What one agent learns, the next one already knows.

MemStack gives Claude Code, Codex and other MCP agents one shared memory per project. Tell one agent a decision; the other recalls it in the same repository, on a store you choose.

Install in two minutes View on GitHub

MIT licensed · Node 22+ · your keys, your database

~/my-project Example

$ npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0
$ memstack init
$ memstack connect claude-code codex
$ memstack doctor

# later, in Claude Code
you    Remember that this project uses Hono.
claude Saved to project memory.

# next day, in Codex, same repository
you    What framework does this project use?
codex  Hono.

5tools per agent in the harness profile

1command connects each agent

5stores: SQLite, Postgres, Redis, disk, markdown

0LLM calls to recall a memory

How it works

Four jobs, one memory per project.

Coding agents forget everything between sessions and cannot see what each other learned. MemStack saves durable facts through MCP and loads the important ones when a session starts.

Save

Say “remember that…”, or let the agent store a durable fact, decision or rule. MemStack asks your LLM for a few topic tags, so “uses Hono” is found later by “which framework?”. If tagging fails, the memory is still saved.

memory_store({
  content: "This project uses Hono for the API",
  scope:   "project"   // or "global"
})

Recall

A session-start hook loads the project’s most important memories before the first prompt. During a session the agent asks plain questions. Recall is keyword ranking (BM25 with stemming) that runs locally, so it is fast and works offline.

memory_retrieve({
  query: "which framework do we use?"
})

Scope

Memories belong to the repository. The project ID comes from the repo itself, so it survives clones, worktrees, renamed remotes and moved folders. Preferences that apply everywhere can be saved as global. One project cannot read or delete another’s memories.

$ memstack project
$ memstack project pin my-app   # writes .memstack.json

Stay in control

Agents get no bulk or destructive tools. Your LLM key lives in ~/.memstack/config.json, readable only by you, never in agent configs. connect backs up every file it touches and disconnect restores each one exactly.

$ memstack connect codex --dry-run
$ memstack disconnect codex

Install

Pick your agent, copy the commands.

Claude Code and Codex have a one-command connect. Every other MCP client uses a short config block with the full 18-tool server.

One-command connect

Claude Code

Adds a user-scope memstack MCP server and a SessionStart hook.
Installs the harness profile: project-scoped, shared with Codex.
Restart Claude Code afterwards, then run /mcp to check.

terminal

npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0
memstack init
memstack connect claude-code
memstack doctor

MemStack never installs storage drivers for you. better-sqlite3 is the SQLite driver; pick another store in memstack init.

One-command connect

Codex

Registers the server with codex mcp add and a SessionStart hook in hooks.json.
Adds a short marked block to ~/.codex/AGENTS.md, because Codex gives MCP instructions little weight.
Start a new session, then approve the hook once with /hooks.

terminal

npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0
memstack init
memstack connect codex
memstack doctor

Manual config · full profile

opencode

Put this in opencode.json in the project root, or ~/.config/opencode/opencode.json.
command is one array, and variables go under environment.
Check with opencode mcp list. There is no memstack connect opencode yet.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memstack": {
      "type": "local",
      "command": ["npx", "-y", "-p", "@memstack/mcp",
                  "-p", "better-sqlite3@^11.10.0", "memstack-mcp"],
      "enabled": true,
      "environment": {
        "MEMSTACK_STORAGE": "sqlite",
        "SQLITE_PATH": "/Users/me/.memstack/memstack.db",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Manual config · full profile

Cursor

Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.
Cursor Settings → MCP should show the server with an active dot and its tools.

.cursor/mcp.json

{
  "mcpServers": {
    "memstack": {
      "command": "npx",
      "args": ["-y", "-p", "@memstack/mcp",
               "-p", "better-sqlite3@^11.10.0", "memstack-mcp"],
      "env": {
        "MEMSTACK_STORAGE": "sqlite",
        "SQLITE_PATH": "/Users/me/.memstack/memstack.db",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Manual config · full profile

Gemini CLI

Add it to .gemini/settings.json in the project, or ~/.gemini/settings.json for every project.

.gemini/settings.json

{
  "mcpServers": {
    "memstack": {
      "command": "npx",
      "args": ["-y", "-p", "@memstack/mcp",
               "-p", "better-sqlite3@^11.10.0", "memstack-mcp"],
      "env": {
        "MEMSTACK_STORAGE": "sqlite",
        "SQLITE_PATH": "/Users/me/.memstack/memstack.db",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Manual config · full profile

Any MCP client

Most clients wrap the same command, args and env. Some use another top-level key: mcpServers, mcp, context_servers or servers.
Test the server on its own first with the MCP Inspector.
The default profile needs an OPENAI_API_KEY or ANTHROPIC_API_KEY. With MEMSTACK_STORAGE=memory nothing survives a restart.

terminal

npx -y @modelcontextprotocol/inspector npx -y @memstack/mcp

mcp.json

{
  "mcpServers": {
    "memstack": {
      "command": "npx",
      "args": ["-y", "@memstack/mcp"],
      "env": {
        "MEMSTACK_STORAGE": "memory",
        "OPENAI_API_KEY": "sk-...",
        "MEMSTACK_ACTOR": "my-agent"
      }
    }
  }
}

TypeScript SDK

As a library

For an application that owns its own memory: store, retrieve, compile context, summarize and prune.
Works with OpenAI, DeepSeek, OpenRouter, Together, Gemini or any OpenAI-compatible API. Omit the embedding adapter and retrieval falls back to keyword, recency and importance.

memory.ts

import { MemStack, OpenAILLMAdapter, InMemoryStorageAdapter } from "@memstack/core";

const memstack = new MemStack({
  llm: new OpenAILLMAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  storage: new InMemoryStorageAdapter(),
});

await memstack.memory.store({
  actorId: "support-bot-42",
  content: "User reports login failing with error 503 on Chrome 125.",
  tags: ["login", "bug"],
  importance: 0.8,
});

const ctx = await memstack.memory.compileContext({
  actorId: "support-bot-42",
  maxTokens: 2000,
});

npm install @memstack/core

Reference

Seven commands. Five stores.

Run memstack doctor first when something looks wrong. It checks the config file, the LLM key, the storage driver, each agent’s registration, hook and guidance, and starts the server to confirm it answers.

Storage drivers are yours to install. MemStack never bundles or auto-installs them, so choose SQLite for one local file, or Postgres to share across machines.

Command	What it does
`memstack init`	Choose an LLM provider and a store. Verifies the key with a real request.
`memstack connect <agent>`	Registers MemStack with Claude Code or Codex. Checks the server first and undoes everything if a step fails.
`memstack disconnect <agent>`	Removes what `connect` added. Your memories are kept.
`memstack status`	Config, storage, the current project and what each agent has connected.
`memstack doctor`	Diagnoses setup problems and prints the fix. `--live` also tests the LLM key.
`memstack memories [query]`	List or search this project’s memories. `--delete <id>` removes one.
`memstack project`	Show the project ID. `pin` fixes it in `.memstack.json`; `merge` moves memories from an old ID.

Store	Driver to install	Notes
`sqlite`	`better-sqlite3@^11.10.0`	Default. One local file, safe for both agents at once.
`postgres`	`postgres@^3.4.9`	Shared across machines.
`redis`	`ioredis@^5.11.1`
`disk`, `markdown`	none	Single process only.

Guides

Where to go after it works.

The full documentation lives in the repository. These are the pages people reach for first.

StartHarness memory for Claude Code and CodexHow saving, recall, scope and safety work, and what connect changes on disk. SetupMCP setup for every clientCopy-paste config for Claude Desktop, Cursor, Windsurf, Cline, Continue, VS Code, Zed, opencode, Gemini CLI and Goose. ConceptHow a project is identifiedPinned ID, first commit, origin remote. Why forks share memory until you pin one. ConfigChoosing and switching storageDrivers, trade-offs, and moving memories with export and import. FixTroubleshootingMissing driver, Codex not loading memories at start, memories that seem to be missing. SDKThe memory pipelineStore, retrieve, compile context, summarize and prune, with token budgets. ReferenceMCP server referenceEvery tool, resource and prompt, plus the stdio and Streamable HTTP transports.

For agents

Let the agent set itself up.

Paste the prompt, or give your agent the skill. It runs the same commands a person would, and stops where a decision is yours.

prompt

Set up MemStack so you and my other coding agents share one
memory per project. Run `memstack status` first. If this agent
is not connected, tell me to run:

  npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0
  memstack init
  memstack connect <claude-code|codex>

Never install storage drivers yourself, and never store
secrets. When I say "remember ...", call memory_store. At the
start of a task, call memory_retrieve.

agent skill

npx skills add isiomaC/memstack -g

The skill

The memstack-cli skill teaches compatible agents to check memstack status, use the project-scoped tools inside Claude Code and Codex, and fall back to the shell only when they must. Omit -g to install it for one project.

Machine-readable docs

llms.txt on this site summarises MemStack for models. GitMCP serves the repository as an MCP docs endpoint at gitmcp.io/isiomaC/memstack.

Rules agents follow

Store one self-contained statement per memory. Recall before decisions that depend on history. Never store secrets, credentials or personal data. Cite memory IDs when relying on them.

Resources

Everywhere MemStack is published.

Four npm packages, a container image, two directory listings and an agent skill.

npm@memstack/cliShell tool. init, connect, doctor and the rest.npm install -g @memstack/cli npm@memstack/mcpThe MCP server. Add --profile harness for coding agents.npx -y @memstack/mcp npm@memstack/coreThe runtime SDK for applications that own their memory.npm install @memstack/core npm@memstack/serverA shared HTTP API for several applications.npx @memstack/server Containermemstack-server imageThe REST API without installing Node. Not an MCP image.ghcr.io/isiomac/memstack-server SourceGitHub repositoryCode, issues, changelog, contributing and security policy.github.com/isiomaC/memstack DirectoryMCP RegistryThe official MCP Registry entry for @memstack/mcp.io.github.isiomaC/memstack DirectoryGlamaA hosted listing with an inspector and a quality score.glama.ai/mcp/servers/isiomaC/memstack Agent skillskills.shThe memstack-cli skill for Claude Code, Codex and other agents.npx skills add isiomaC/memstack -g LLM docsGitMCPPoint an agent at the repository as a documentation MCP endpoint.gitmcp.io/isiomaC/memstack

Straight answers

What leaves your machine, and what doesn’t.

Short answers to the questions that decide whether you can use it.

Where is my memory stored?

In the store you pick in memstack init: a local SQLite file by default, or Postgres, Redis, disk or markdown. MemStack has no hosted service. The only data that reaches a third party is what your own LLM provider receives for tagging and summarising.

Does recalling a memory call an LLM?

No. Recall is local keyword ranking, so it is fast and works offline. Saving a memory asks your LLM for a few topic tags, and the memory is still saved if that fails.

Can an agent store my secrets?

Agents are told never to store secrets, credentials or personal data, but MemStack does not scan memories for them. Treat the store as you would any file holding project notes, and delete a bad memory with memstack memories --delete <id>.

Why do two forks share memories?

The project ID comes from the repository’s first commit, which a fork shares with its origin. On one store, run memstack project pin <id> in one of them to separate them.

Which agents work today?

Claude Code and Codex have the harness profile, project scoping and session-start recall through memstack connect. Any other MCP client works with the manual config and the full 18-tool server. The harness profile speaks stdio only.

Is it only an MCP server?

No. It is also a TypeScript SDK (@memstack/core), a CLI, and a REST server for sharing memory between applications.