# agent-memory-os

agent-memory-os — a local MCP server gives agent teams shared, access-controlled memory with project scopes and node sync. Use it when several agents need the same context.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 9 repo stars
- Author: yamantaka520
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/yamantaka520/Agent-Memory-OS
- Updated: 2026-10-01
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/agent-memory-os

## What it does

\`agent-memory-os` keeps agent memory in a single SQLite database with FTS5 indexing. Records can belong to an agent, team, project, or global scope, and the access check runs before ranking. Linked memories can surface through associative recall, while each prompt receives a token-budgeted context pack with an audit of included and excluded items.

The server can exchange memories and organization data between nodes using bundles and peer synchronization. It also handles duplicate merging, conflict markers, decay, pinning, expiry, and access revocation. A web UI, vector candidates, and the MCP server are optional sidecars. Set `AGENT_MEMORY_AGENT_ID` when agents need separate identities, and use `AGENT_MEMORY_HOME` to choose the memory location.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `AGENT_MEMORY_AGENT_ID`, `AGENT_MEMORY_HOME` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env AGENT_MEMORY_AGENT_ID=<AGENT_MEMORY_AGENT_ID> --env AGENT_MEMORY_HOME=<AGENT_MEMORY_HOME> --transport stdio agent-memory-os -- uvx agent-memory-os
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-memory-os <command>

### Codex

**Platform CLI**
```bash
codex mcp add agent-memory-os --env AGENT_MEMORY_AGENT_ID=<AGENT_MEMORY_AGENT_ID> --env AGENT_MEMORY_HOME=<AGENT_MEMORY_HOME> -- uvx agent-memory-os
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-memory-os <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "agent-memory-os": {
            "command": "uvx",
            "args": [
                "agent-memory-os"
            ],
            "env": {
                "AGENT_MEMORY_AGENT_ID": "<AGENT_MEMORY_AGENT_ID>",
                "AGENT_MEMORY_HOME": "<AGENT_MEMORY_HOME>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-memory-os <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "agent-memory-os": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "agent-memory-os"
            ],
            "env": {
                "AGENT_MEMORY_AGENT_ID": "<AGENT_MEMORY_AGENT_ID>",
                "AGENT_MEMORY_HOME": "<AGENT_MEMORY_HOME>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-memory-os <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e AGENT_MEMORY_AGENT_ID=<AGENT_MEMORY_AGENT_ID> -e AGENT_MEMORY_HOME=<AGENT_MEMORY_HOME> agent-memory-os uvx agent-memory-os
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-memory-os <command>

## When to use it
- store durable memory for several AI agents
- separate records by team and project
- enforce access rules before recall
- sync memory across multiple nodes
- surface related records without shared query terms

## Example prompts
- Save this architecture decision as team memory and limit access to the agents in this project.
- Find earlier decisions about this module, including linked memories that use different terms.
- Build a context pack for this request using only memories visible to the current agent.

## Similar
- [Vector Search — In-Memory TF-IDF Semantic Store](https://affpapa.org/en/nevibecode/mcp/vector-search-in-memory-tf-idf-semantic-store.md) — MCP server · 3562 installs
- [OMEGA Memory](https://affpapa.org/en/nevibecode/mcp/omega-memory-omega-memory.md) — MCP server · 2862 installs
- [deep-agents-memory](https://affpapa.org/en/nevibecode/skills/deep-agents-memory.md) — skill · 20000 installs
- [memory-safety-patterns](https://affpapa.org/en/nevibecode/skills/memory-safety-patterns.md) — skill · 11746 installs
- [memory-management](https://affpapa.org/en/nevibecode/skills/memory-management.md) — skill · 7800 installs
- [memory-discipline](https://affpapa.org/en/nevibecode/skills/memory-discipline.md) — skill · 4900 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
