{"_id":"n2n-memory","name":"n2n-memory","dist-tags":{"latest":"1.2.2"},"versions":{"1.2.2":{"name":"n2n-memory","version":"1.2.2","description":"Project-local knowledge-graph memory MCP server from N2NS Lab for AI coding agents.","main":"build/index.js","bin":{"n2n-memory":"build/index.js"},"repository":{"type":"git","url":"git+https://github.com/n2ns/n2n-memory.git"},"homepage":"https://github.com/n2ns/n2n-memory#readme","bugs":{"url":"https://github.com/n2ns/n2n-memory/issues"},"type":"module","scripts":{"clean":"node -e \"require('node:fs').rmSync('build', { recursive: true, force: true })\"","build":"npm run clean && tsc -p tsconfig.build.json","start":"node build/index.js","dev":"tsx src/index.ts","test":"vitest run","lint":"eslint src/**/*.ts","audit":"npm audit","audit:prod":"npm audit --omit=dev","pack:dry-run":"npm pack --dry-run","check":"npm run lint && npm test && npm run build && npm run audit && npm run pack:dry-run","prepublishOnly":"npm run check"},"keywords":["mcp","mcp-server","model-context-protocol","modelcontextprotocol","memory","agent-memory","ai-memory","project-memory","project-local-memory","project-local-knowledge-graph","mcp-memory-server","coding-agent-memory","repository-memory","repository-context","context-memory","local-first-memory","coding-assistant-memory","project-memory-server","context","ai","ai-developer-tools","coding-agent","local-first","claude","claude-desktop","cursor","vscode","knowledge-graph"],"author":{"name":"N2NS Lab"},"license":"MIT","engines":{"node":">=20","npm":">=10.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","@types/proper-lockfile":"^4.1.4","async-mutex":"^0.5.0","fs-extra":"^11.3.5","proper-lockfile":"^4.1.2","zod":"^4.4.3"},"devDependencies":{"@types/chai":"^5.2.3","@types/fs-extra":"^11.0.4","@types/node":"^25.0.3","@types/sinon":"^21.0.0","@typescript-eslint/eslint-plugin":"^8.50.0","@typescript-eslint/parser":"^8.50.0","chai":"^6.2.1","eslint":"^9.39.2","sinon":"^21.0.1","tsx":"^4.21.0","typescript":"^5.9.3","typescript-eslint":"^8.50.0","vitest":"^4.1.8"},"gitHead":"0d351a5ead51552b445f07e8788601bd3f11c655","_id":"n2n-memory@1.2.2","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-VDgAaaHcWQmyd5RYkBIch9B3sw4ivrJ+oiTAdLoIpefbyU8ka/Nti2e+AznlE9GpQmHbyCzXVlTFocY29A5g9g==","shasum":"3ba9c0dc38d6d05fb552d62e6a4d8abf16c8961c","tarball":"https://registry.npmjs.org/n2n-memory/-/n2n-memory-1.2.2.tgz","fileCount":36,"unpackedSize":197589,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDdtefyKoZYfcishSv+jOAOrufdyAYiRZ0d0NhfzYL1KAIgYTCIyqkiRju7umC691R+t31v4JWgYTZZtfnwpumr0Zs="}]},"_npmUser":{"name":"bugstan","email":"out4null@gmail.com"},"directories":{},"maintainers":[{"name":"bugstan","email":"out4null@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n2n-memory_1.2.2_1781405215710_0.6550939344695887"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-14T02:46:55.662Z","1.2.2":"2026-06-14T02:46:55.848Z","modified":"2026-06-14T02:46:56.044Z"},"maintainers":[{"name":"bugstan","email":"out4null@gmail.com"}],"description":"Project-local knowledge-graph memory MCP server from N2NS Lab for AI coding agents.","homepage":"https://github.com/n2ns/n2n-memory#readme","keywords":["mcp","mcp-server","model-context-protocol","modelcontextprotocol","memory","agent-memory","ai-memory","project-memory","project-local-memory","project-local-knowledge-graph","mcp-memory-server","coding-agent-memory","repository-memory","repository-context","context-memory","local-first-memory","coding-assistant-memory","project-memory-server","context","ai","ai-developer-tools","coding-agent","local-first","claude","claude-desktop","cursor","vscode","knowledge-graph"],"repository":{"type":"git","url":"git+https://github.com/n2ns/n2n-memory.git"},"author":{"name":"N2NS Lab"},"bugs":{"url":"https://github.com/n2ns/n2n-memory/issues"},"license":"MIT","readme":"# n2n-memory\n\nProject-local knowledge-graph memory MCP server from N2NS Lab for AI coding agents.\n\n[![npm version](https://img.shields.io/npm/v/n2n-memory)](https://www.npmjs.com/package/n2n-memory)\n[![npm total downloads](https://img.shields.io/npm/dt/n2n-memory)](https://www.npmjs.com/package/n2n-memory)\n[![license](https://img.shields.io/github/license/n2ns/n2n-memory)](https://github.com/n2ns/n2n-memory/blob/main/LICENSE)\n[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)\n[![node version](https://img.shields.io/node/v/n2n-memory)](https://nodejs.org)\n[![DataFrog.io](https://datafrog.io/badges/datafrog.svg)](https://datafrog.io)\n\n[中文版](./docs/README_zh.md)\n\n---\n\n> **Context as code. Memory as asset.**\n\nn2n-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.\n\n### Search-friendly positioning\n\nIf you are searching for:\n- AI coding memory\n- project-local MCP memory\n- local-first context memory for coding agents\n- repository-isolated memory graph for Claude/Cursor/VS Code workflows\n\nThis server is designed for these goals: deterministic JSON output, project isolation, and Git-friendly reviewability.\n\n## What Is n2n-memory?\n\nn2n-memory gives AI coding tools a project-local knowledge graph they can read and update through MCP. It is designed for developers and teams who use AI assistants across multiple repositories and want memory that is local, auditable, Git-friendly, and not mixed with unrelated projects.\n\n**TL;DR**\n- **Install**: `npx -y n2n-memory`\n- **Protocol**: Model Context Protocol (MCP), stdio transport\n- **Storage**: `.mcp/memory.json` for durable memory, `.mcp/context.json` for active task state\n- **Best for**: AI coding assistant memory, project architecture notes, shared team context\n- **Not for**: cloud sync, global personal memory, source code indexing, or vector database replacement\n\n### 🌟 Key Highlights\n- **Project-Level Physical Isolation**: Memory and active context are stored under `[Project Root]/.mcp/`.\n- **Git-Friendly**: JSON data is automatically sorted by key to generate clean and readable `git diff`.\n- **Dual-Buffer State**: Durable graph knowledge lives in `memory.json`; high-frequency task state lives in `context.json`.\n- **Tool Agnostic**: Uses the `.mcp` naming convention, not tied to any specific AI brand or IDE plugin.\n- **Assets for Your Code**: Memory stays with your code; team members can share AI's understanding of the architecture by simply pulling the repository.\n- **Universal Compatibility**: Works with MCP-enabled clients and AI coding tools that support stdio MCP servers.\n- **Privacy-First**: Built with security by design, keeping your data local and isolated.\n\n## Use Cases\n\n- Restore project context at the start of an AI coding session.\n- Preserve architecture decisions, implementation notes, known pitfalls, and active task state.\n- Share durable project memory with teammates through Git.\n- Keep memory isolated per repository when working across many client, product, or open-source projects.\n- Query a local project knowledge graph without adding a database or cloud service.\n\n## How It Compares\n\n| Approach | Best for | Tradeoff |\n| --- | --- | --- |\n| n2n-memory | Project-local MCP memory for AI coding agents | Requires assistants to call MCP tools intentionally |\n| Global MCP memory | Personal memory across many chats or projects | Can mix unrelated project context |\n| Markdown memory bank | Human-readable project notes | Less structured for graph queries and tool updates |\n| Vector database memory | Semantic retrieval over large corpora | Heavier infrastructure and less deterministic diffs |\n| IDE-specific rules | Steering assistant behavior in one IDE | Less portable across MCP clients |\n\n### 🚀 Quick Start\n\n#### 1. Installation & Config (IDE / Claude Desktop)\n\nThe easiest way to use this is via `npx`:\n\n##### Claude Desktop\nFile Path: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"n2n-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"n2n-memory\"]\n    }\n  }\n}\n```\n\n##### Cursor / VSCode (MCP Plugin)\nAdd in the MCP settings panel:\n- **Name**: `n2n-memory`\n- **Type**: `command`\n- **Command**: `npx -y n2n-memory`\n\n##### Other MCP clients\n- The server uses stdio MCP and can be wired to any MCP client that supports local command execution.\n- If your client supports it, set `N2N_LOG_LEVEL=debug` only when troubleshooting local path resolution.\n\n#### 2. Usage Guide\n\nThis service is path-driven. AI assistants should pay attention to:\n\n1. **Absolute Project Root**: When calling any `n2n_*` tool, provide the absolute path of the current project root or workspace top-level directory (`projectPath`).\n2. **Initialization Handshake**: If `.mcp` does not exist yet, call the tool again with `confirmNewProjectRoot` set to the detected root returned by the server.\n3. **Auto Storage**: Durable memory is saved to `[ProjectPath]/.mcp/memory.json`; active task context is saved to `[ProjectPath]/.mcp/context.json`.\n4. **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.\n\nRecommended `.gitignore` policy for teams that want to share durable memory:\n\n```gitignore\n.mcp/context.json\n!.mcp/\n!.mcp/memory.json\n```\n\nIf your project memory may contain private implementation details, keep the whole `.mcp/` directory ignored.\n\n##### Available Tools:\n- `n2n_add_entities`: Create new entities.\n- `n2n_add_observations`: Append observations or facts.\n- `n2n_create_relations`: Establish connections between existing entities.\n- `n2n_read_graph`: Read project memory and active context (Supports `summaryMode` and `pagination`).\n- `n2n_get_graph_summary`: Quickly fetch a lightweight index of all entities (Supports `pagination`).\n- `n2n_update_context`: Update current task status and next steps.\n- `n2n_search`: Search the graph via keyword or fuzzy matching (Supports `pagination`).\n- `n2n_delete_entities`: Remove entities and their attached relations.\n- `n2n_delete_observations`: Remove specific observations from entities.\n- `n2n_delete_relations`: Remove specific relations.\n- `n2n_open_nodes`: Retrieve specific entities by name.\n- `n2n_export_markdown`: Export the graph to a Markdown file inside the project root.\n\n##### Safety Notes:\n- Existing but unreadable JSON files are treated as data integrity errors, not as empty memory.\n- Export paths must be relative and must stay inside the project root.\n- Relations that point to missing entities are rejected.\n- 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.\n- Full local paths are hidden from server logs by default. Set `N2N_LOG_LEVEL=debug` when diagnosing path issues.\n\n### 🗺️ Future Roadmap\n- **Semantic Search**: Integration of minimalist Vector Embeddings for fuzzy memory retrieval.\n- **Ontology Enforcement**: Optional schema for relation type consistency.\n- **Time Travel**: Versioned snapshots for memory rollback.\n\n## Security and governance notes\n\n- `n2n_delete_entities`, `n2n_delete_observations`, and `n2n_delete_relations` are destructive and should be governed by review workflows.\n- Keep `context.json` uncommitted by default, and commit `.mcp/memory.json` only when team sharing is intentional.\n- See [SECURITY.md](./SECURITY.md) for vulnerability reporting.\n\n### Search disambiguation note\n\n`n2n-memory` is not a network VPN or mesh overlay project. It is an MCP memory server for AI coding agents.\n\n## FAQ\n\n### Is n2n-memory a vector database?\n\nNo. n2n-memory stores a deterministic JSON knowledge graph. Semantic search may be added later, but the core design is structured, Git-friendly project memory.\n\n### Should I commit `.mcp/memory.json`?\n\nCommit `.mcp/memory.json` when the knowledge graph is useful to your team. Keep it ignored if it may contain private implementation details. `context.json` is active task state and is often better left uncommitted.\n\n### Does n2n-memory send data to the cloud?\n\nNo. n2n-memory is a local MCP server. It reads and writes files under your project directory.\n\n### How is this different from global memory?\n\nGlobal memory follows the assistant or user across contexts. n2n-memory follows the repository, so unrelated projects do not contaminate each other's memory.\n\n### Does it work with Claude Desktop, Cursor, and VS Code?\n\nYes, when the client supports stdio MCP servers. The README includes Claude Desktop and Cursor / VS Code MCP configuration examples.\n\n### Is this the same as a global AI memory store?\n\nNo. This is a repository-scoped memory server. Each project gets its own `.mcp` workspace.\n\n---\n\n## 📖 Related Docs\n\n- **[Design Solution](./docs/DESIGN.md)**: Why project-level isolation?\n- **[API Reference](./docs/API_REFERENCE.md)**: Tool descriptions and schema.\n- **[Development](./docs/DEVELOPMENT.md)**: How to build, test and extend.\n- **[Changelog](./CHANGELOG.md)**: Version history and incident recovery.\n- **[llms.txt](./llms.txt)**: Short AI-readable project summary for coding agents and answer engines.\n\n## 📄 License\nThis project is licensed under the [MIT License](./LICENSE).\n\n---\n\nBuilt by N2NS Lab, short for Next-to-Native Systems Lab, Datafrog's open-source lab for practical AI developer tools.\n","readmeFilename":"README.md","_rev":"1-8f646a1928869344ef206eabf5034179"}