Agentsmd Memory

npm ci license

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.

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.

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

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

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

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

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

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

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

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

opencode plugin (recommended)

The tools are prompt-driven — the agent only calls them if it decides to, which rarely happens mid-task. The package ships plugins for opencode and Claude Code that inject a short reminder every turn (opencode via the system prompt, Claude Code 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 the reminder text with the MEMORY_NUDGE env var.

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

• 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. The bundled opencode plugin nudges it every turn.

Develop

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

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

License

MIT