Skip to main content
Glama
n2ns
by n2ns

n2n-memory

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

npm version npm total downloads license MCP Protocol node version

中文版


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

Related MCP server: Memento

💡 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.

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, 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.

📄 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.

Available Tools

12 tools
n2n_add_entitiesD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
entitiesYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_add_observationsD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
observationsYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_create_relationsD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
relationsYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_delete_entitiesD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
entityNamesYesNames of entities to delete

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_delete_observationsD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
deletionsYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_delete_relationsD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
relationsYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_export_markdownD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
outputPathNoOutput file path relative to project root, defaults to KNOWLEDGE_GRAPH.md

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_get_graph_summaryD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
limitNoMaximum number of entities to return.
offsetNoNumber of entities to skip.

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_open_nodesD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
namesYesNames of entities to retrieve

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_read_graphD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
summaryModeNoIf true, returns only entity names and types without detailed observations to save tokens.
limitNoMaximum number of entities to return.
offsetNoNumber of entities to skip.

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

n2n_update_contextD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project or any subdirectory within the project.
confirmNewProjectRootNoMUST be provided ONLY when initializing a new project. Set this to the 'detectedRoot' path returned by the server's confirmation request.
activeTaskNoCurrent task being performed
statusNoCurrent project status
reasonNoReason for current status (especially if BLOCKED)
nextStepsNoPlanned subsequent actions
lastCommitNoHash or message of the last relevant git commit

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

C2.1/5.0
Disambiguation5/5

Each tool targets a distinct operation (add, delete, create, read, search, update) on specific resources (entities, observations, relations, graph). No overlap in purpose despite missing descriptions.

Naming Consistency5/5

All tools follow the consistent pattern 'n2n_<verb>_<noun>' using snake_case. The verb choices are clear and the noun targets are explicit.

Tool Count5/5

12 tools cover the typical operations for a memory/knowledge graph server without being excessive or sparse. The scope feels well-balanced.

Completeness4/5

The set covers add, delete, and read operations for entities and observations, plus relations and graph exports. Missing update operations for some resources, but the core workflows are present.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    Provides persistent memory for AI tools by building a local knowledge graph from conversations, enabling cross-session recall and context awareness without cloud dependencies.
    9
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Provides a local long-term memory layer for AI coding tools like Cursor and Claude Code, enabling cross-session, cross-tool sharing of project facts, user preferences, decisions, and workflows.
    25
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/n2ns/n2n-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server