agentsmd-memory

MCP server for keeping project memory in AGENTS.md. Zero dependencies.

The tools don't edit files. They resolve the nearest memory file and return instructions the agent carries out with its own Write/Edit tools, so every change — even creating the file — shows up as a reviewable git diff.

Tools

• memory_save — record a durable fact (decision, convention, gotcha, non-obvious command).

• memory_forget — remove a stale fact.

Related MCP server: Agent Memory MCP

Install

Published on npm as agentsmd-memory. Runs via npx — no global install needed. The config schema differs per client; expand yours below. On Windows, wrap the command as cmd /c npx -y agentsmd-memory.

Installs the MCP tools and same per-turn UserPromptSubmit nudge used by Claude Code:

codex plugin marketplace add https://github.com/jryom/agentsmd-memory.git
codex plugin add agentsmd-memory@agentsmd-memory

Restart Codex after installation. Review and enable the plugin hook with /hooks; Codex requires explicit trust for plugin hooks. Override reminder text with MEMORY_NUDGE.

Installs the MCP tools and a per-turn nudge in one step (see why the nudge helps; Claude Code delivers it via a UserPromptSubmit hook):

claude plugin marketplace add jryom/agentsmd-memory
claude plugin install agentsmd-memory@agentsmd-memory

Override the reminder text with the MEMORY_NUDGE env var. No file config needed: the tools prefer AGENTS.md and fall back to CLAUDE.md, which Claude Code auto-loads (see Config).

Tools without the nudge:

claude mcp add --transport stdio memory -- npx -y agentsmd-memory

claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "agentsmd-memory"]
    }
  }
}

~/.config/opencode/opencode.json. Note the differences: top-level mcp (not mcpServers), command is a single array, env goes in environment (not env).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "agentsmd-memory"],
      "enabled": true
    }
  },
  "plugin": ["agentsmd-memory"]
}

The plugin line is recommended — see per-turn reminder. It loads from npm by name, so it requires agentsmd-memory >= 1.2.0; restart opencode after editing.

.vscode/mcp.json (project) or your user mcp.json. Top-level key is servers and the type is stdio:

{
  "servers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "agentsmd-memory"]
    }
  }
}

copilot mcp add memory -- npx -y agentsmd-memory

Or edit ~/.copilot/mcp-config.json directly. Copilot CLI requires type: "local" and a tools field:

{
  "mcpServers": {
    "memory": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "agentsmd-memory"],
      "tools": ["*"]
    }
  }
}

Repo → Settings → Copilot → MCP servers. Same shape as the CLI (type: "local", tools required). Any env vars must be prefixed COPILOT_MCP_.

{
  "mcpServers": {
    "memory": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "agentsmd-memory"],
      "tools": ["*"]
    }
  }
}

Per-turn reminder

The tools are prompt-driven — the agent only calls them if it decides to, which rarely happens mid-task. The package ships integrations for opencode, Claude Code, and Codex that inject a short reminder every turn (opencode via the system prompt; Claude Code and Codex via a UserPromptSubmit hook), so the agent reliably reaches for memory_save/memory_forget. The opencode plugin is enabled via the "plugin": ["agentsmd-memory"] line in the config above. Override reminder text with MEMORY_NUDGE.

Config

When MEMORY_FILE is unset the tools prefer AGENTS.md, then fall back to CLAUDE.md. So a Claude Code repo that only has CLAUDE.md (which Claude auto-loads; it doesn't read AGENTS.md) is found without any config, while AGENTS.md stays preferred for cross-tool sharing when present.

Notes

• Claude Code and Codex plugin installs launch the MCP server through unpinned npx -y agentsmd-memory, intentionally following npm's latest tag. npm may download package code on startup and caches fetched packages.

• Workspace dir is resolved from MCP roots, else a cwd arg, else process.cwd(). From there it walks up to the git root; the nearest existing file wins, and at a given level AGENTS.md beats the CLAUDE.md fallback. When nothing exists, AGENTS.md is created at the git root.

• The tools never write files. When no memory file exists, memory_save returns instructions to create one; the agent authors it with its own Write tool, so even bootstrapping shows up as a reviewable diff.

• Saves are prompt-driven; the agent decides when to call them. Bundled integrations nudge it every turn.

Develop

npm test
npx @modelcontextprotocol/inspector npx -y agentsmd-memory

Source: github.com/jryom/agentsmd-memory.

License

MIT