n2n-memory MCP server
Commit Oct 27, 2026Provides AI coding agents with a project-local knowledge graph stored in Git-friendly JSON files for isolated, shareable project memory.
Also known as n2ns/n2n-memory
- Stars
- 11
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 27, 2026
- License
- Apache-2.0
What is n2n-memory MCP?
n2n-memory provides AI coding agents with a project-local knowledge graph stored in Git-friendly JSON files for isolated, shareable project memory. It exposes 12 tools, such as n2n_add_entities, n2n_add_observations, n2n_create_relations.
Summary generated from the project's README
About n2n-memory MCP server
Providing AI coding agents with a project-specific knowledge graph is the primary function of n2n-memory. This local-first MCP server allows developers to store architecture decisions, implementation notes, and known pitfalls directly within a repository. By using a path-driven approach, it ensures that memory remains isolated to each individual project, preventing information from leaking between different codebases.
Users can set up the server in Claude Desktop, Cursor, or VS Code using the command npx -y n2n-memory. The system manages two distinct files: memory.json for durable knowledge and context.json for active task states. Because these files are stored in a .mcp directory, they are Git-friendly and can be committed to share project intelligence with teammates. The server uses stdio to communicate with MCP clients and requires the absolute project root path to be passed to its tools during operation.
What you can do with it
- 1Share project intelligence with teammatesA developer can commit the knowledge graph to a repository so that other team members' AI assistants can access the same architectural context.
- 2Maintain isolated context across multiple repositoriesAn AI agent can work on several different projects without mixing up the specific implementation details or rules of each one.
- 3Document and retrieve architectural decisionsYou can instruct an AI to record specific implementation notes or pitfalls into a searchable graph for future reference.
- 4Manage active task states during handoffsAn AI assistant can update its current progress and task context before a developer finishes a session.
Written from the project's README. Every use case is checked against a quote from it.
How to install n2n-memory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall n2n-memory MCP in Claude Code
$ claude mcp add n2n-memory -- npx -y n2n-memoryInstall n2n-memory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"n2n-memory": {
"command": "npx",
"args": [
"-y",
"n2n-memory"
]
}
}
}Install n2n-memory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"n2n-memory": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"n2n-memory"
]
}
}
}Install n2n-memory MCP in VS Code CLI
$ code --add-mcp '{"name":"n2n-memory","type":"stdio","command":"npx","args":["-y","n2n-memory"]}'Install n2n-memory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"n2n-memory": {
"command": "npx",
"args": [
"-y",
"n2n-memory"
]
}
}
}Install n2n-memory MCP in Codex
$ codex mcp add n2n-memory -- npx -y n2n-memoryInstall n2n-memory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.n2n-memory] command = "npx" args = ["-y", "n2n-memory"]
Install n2n-memory MCP in Gemini CLI
$ gemini mcp add -s user n2n-memory npx -- -y n2n-memoryInstall n2n-memory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"n2n-memory": {
"command": "npx",
"args": [
"-y",
"n2n-memory"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for n2n-memory 1.2.2 in an isolated container with no network and no keys. It answered and listed 12 tools.
n2n-memory MCP tools 12
Read from the server with tools/listn2n_add_entitiesn2n_add_observationsn2n_create_relationsn2n_read_graphn2n_get_graph_summaryn2n_update_contextn2n_searchn2n_delete_entitiesn2n_delete_observationsn2n_delete_relationsn2n_open_nodesn2n_export_markdown
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablen2ns/n2n-memory is public and reachablegithub.com/n2ns/n2n-memory ↗Pass
- Package names this repository as its sourcen2n-memory names n2ns/n2n-memory as sourcenpmjs.com/package/n2n-memory ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-27github.com/n2ns/n2n-memory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from n2n-memoryPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubn2n-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?
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=debugonly when troubleshooting local path resolution.
2. Usage guide
This service is path-driven. AI assistants should pay attention to:
- Absolute Project Root: When calling any
n2n_*tool, provide the absolute path of the current project root or workspace top-level directory (projectPath). - 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 withstatus: "AWAITING_CONFIRMATION"and adetectedRoot. Call the same tool again withconfirmNewProjectRootset to that exactdetectedRootto 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. - Auto Storage: Durable memory is saved to
[ProjectPath]/.mcp/memory.json; active task context is saved to[ProjectPath]/.mcp/context.json. - Collaboration: Commit
.mcp/memory.jsonwhen the knowledge graph should be shared with the team. Commitcontext.jsononly 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.
| Variable | Description | Default |
|---|---|---|
N2N_LOG_LEVEL |
Set to debug to enable verbose logs when diagnosing local path resolution. Any other value (or unset) uses normal logging with full local paths hidden. |
unset |
🔐 Security and governance notes
n2n_delete_entities,n2n_delete_observations, andn2n_delete_relationsare destructive and should be governed by review workflows.- Keep
context.jsonuncommitted by default, and commit.mcp/memory.jsononly 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=debugwhen 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 Apache-2.0 License.
Built by N2NS Lab, the open-source lab of datafrog.io for practical AI developer tools.
n2n-memory MCP questions
How do I add n2n-memory MCP to Claude Code?
Run claude mcp add n2n-memory -- npx -y n2n-memory in your terminal. Add --scope user to make it available in every project.
How do I add n2n-memory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does n2n-memory MCP provide?
It exposes 12 tools, including n2n_add_entities, n2n_add_observations, n2n_create_relations, n2n_read_graph, n2n_get_graph_summary.
How do I initialize memory in a new project?
The first call to a tool in a new project will return a status of AWAITING_CONFIRMATION and a detectedRoot; you must then call the tool again with confirmNewProjectRoot set to that root.