n2n-memory

Project-local knowledge-graph memory MCP server from N2NS Lab for AI coding agents.

中文版

Context as code. Memory as asset.

n2n-memory is an open-source, local-first Model Context Protocol (MCP) memory server for AI coding assistants. It prevents cross-project memory pollution by storing durable project knowledge in .mcp/memory.json and active task context in .mcp/context.json inside each repository.

📚 Contents

• What is n2n-memory?

• Quick start

• Configuration

• Security and governance notes

• Related docs

Related MCP server: Neo4j Memory Server

💡 What is n2n-memory?

n2n-memory gives AI coding tools a project-local knowledge graph they can read and update through MCP. Memory and context are stored inside each repository under .mcp/, keeping them isolated, Git-friendly, and reviewable.

• Restore project context at the start of an AI coding session.

• Preserve architecture decisions, implementation notes, and known pitfalls.

• Share durable project memory with teammates through Git.

• Keep memory isolated per repository when working across many projects.

🚀 Quick start

1. Configure your MCP client

Claude Desktop

File Path: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor / VS Code

Add in the MCP settings panel:

• Name: n2n-memory

• Type: command

• Command: npx -y n2n-memory

Other MCP clients

• The server uses stdio MCP and can be wired to any MCP client that supports local command execution.

• If your client supports it, set N2N_LOG_LEVEL=debug only when troubleshooting local path resolution.

2. Usage guide

This service is path-driven. AI assistants should pay attention to:

1. Absolute Project Root: When calling any n2n_* tool, provide the absolute path of the current project root or workspace top-level directory (projectPath).

2. Initialization Handshake: The first call in a project that has no .mcp/ yet does not create anything. The server detects the project root and replies with status: "AWAITING_CONFIRMATION" and a detectedRoot. Call the same tool again with confirmNewProjectRoot set to that exact detectedRoot to initialize memory. Folders without a real project marker (.git, package.json, language build files, …) are rejected outright, so memory is never created in an arbitrary directory.

3. Auto Storage: Durable memory is saved to [ProjectPath]/.mcp/memory.json; active task context is saved to [ProjectPath]/.mcp/context.json.

4. Collaboration: Commit .mcp/memory.json when the knowledge graph should be shared with the team. Commit context.json only if your workflow wants active task state shared.

Storage layout inside each project:

<project-root>/
└── .mcp/
    ├── memory.json    # durable knowledge graph — commit to share with the team
    └── context.json   # active task context — usually kept local

Recommended .gitignore policy for teams that want to share durable memory:

.mcp/context.json
!.mcp/
!.mcp/memory.json

If your project memory may contain private implementation details, keep the whole .mcp/ directory ignored.

Available tools

• Graph writes (n2n_add_entities, n2n_add_observations, n2n_create_relations): add entities, observations, and relations to build the knowledge graph.

• Graph reads (n2n_read_graph, n2n_get_graph_summary, n2n_search, n2n_open_nodes): read the full graph, get a lightweight summary, search, or open specific entities.

• Context (n2n_update_context): update active task state before commits and handoffs.

• Maintenance (n2n_delete_entities, n2n_delete_observations, n2n_delete_relations, n2n_export_markdown): delete entities, observations, or relations; export the graph to Markdown.

See Tools reference for parameter schemas and usage notes.

⚙️ Configuration

n2n-memory runs as a stdio MCP server with no CLI subcommands — start it with npx -y n2n-memory (or n2n-memory once installed). Storage location is derived from the projectPath you pass to each tool, not from configuration.

🔐 Security and governance notes

• n2n_delete_entities, n2n_delete_observations, and n2n_delete_relations are destructive and should be governed by review workflows.

• Keep context.json uncommitted by default, and commit .mcp/memory.json only when team sharing is intentional.

• Existing but unreadable JSON files are treated as data integrity errors, not as empty memory.

• Export paths must be relative and must stay inside the project root.

• Relations that point to missing entities are rejected.

• Generic README-only folders are not treated as project roots; use a real project marker such as .git, package.json, or language-specific build files.

• Full local paths are hidden from server logs by default. Set N2N_LOG_LEVEL=debug when diagnosing path issues.

• See SECURITY.md for vulnerability reporting.

📖 Related docs

• Design: Why project-level isolation?

• Tools reference: MCP tool parameter schemas and usage notes.

• Development: How to build, test and extend.

• Roadmap: Planned features and what's coming next.

• Changelog: Version history and incident recovery.

• Contributing: How to report issues and contribute.

• Security: How to report vulnerabilities.

📄 License

This project is licensed under the MIT License.

Built by N2NS Lab, the open-source lab of datafrog.io for practical AI developer tools.