mcp-knowledge-graph: a local JSONL memory store for Claude and other MCP clients

The problem: conversations forget, and Claude has no memory of its own

Every new chat with an MCP-compatible assistant starts from nothing. The model can read files you paste or that it opens through tools, but there is no built-in place to record that a person, a project or a preference exists and should be recalled later. mcp-knowledge-graph fills that gap with a local knowledge graph: entities (people, projects, concepts), relations between them, and observations attached to each entity. The README describes it as "persistent memory for AI models through a local knowledge graph" and says it works with Claude Code and Desktop plus any MCP-compatible platform.

The intended user is an individual developer or power user running an MCP client on their own machine. There is no server component, no account and no network service. The store is one or more JSONL files in a directory you choose, which means you can open them in an editor, diff them in git, or sync them through a folder like Dropbox. That is the whole value proposition, and it is also the whole constraint: memory is as durable as the directory you point it at.

How the storage layer decides where memory.jsonl lives

The server resolves a file path before it does anything else. The README gives a three-step priority. First, if you are working in a project that contains a directory named exactly .aim, memory goes to .aim/memory.jsonl and stays with the project. Second, if there is no project or no .aim directory, it falls back to the configured global directory passed with --memory-path. Third, a named database adds a suffix, so the work context becomes memory-work.jsonl next to the master file.

The master database is always called default in listings and always stored as memory.jsonl. Named databases are optional and, according to the README, are created automatically when a tool call mentions a new context, so there is no migration step to run when you start organising memories by topic.

The safety mechanism is a marker line. Every memory file is expected to begin with {"type":"_aim","source":"mcp-knowledge-graph"}, and the README states that the system refuses to write to files that lack it. That is a deliberate guard against pointing --memory-path at a directory full of unrelated JSONL and having the server append graph records into it. The README is explicit that .aim (the directory name) and _aim (the file marker) are two different things, which is a naming decision that will trip up anyone skimming the docs.

Installing mcp-knowledge-graph and storing a first entity

There is no separate install step described in the README. The server is published to npm as mcp-knowledge-graph and is launched with npx, which fetches and runs it. The package requires Node 22.0.0 or newer according to package.json, and the executable is dist/index.js exposed as the mcp-knowledge-graph binary.

Configuration goes into claude_desktop_config.json or .claude.json. This is the default global setup the README shows, pointing the server at a .aim directory in your home folder:

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ]
    }
  }
}

After the client restarts you should see the aim_ tools available. The README's second option swaps the path for a synced folder such as /Users/yourusername/Dropbox/ai-memory, which is how the author says he keeps his own memories; the trade-off is that cloud sync and a local write-ahead file do not always agree, and the README does not discuss conflict handling.

For project-local memory the setup is one command in the project root:

mkdir .aim

Once that directory exists, tools run from inside the project use .aim/memory.jsonl instead of the global directory, with no config change.

To write the first record, the README shows a store call against the master database, which needs no context parameter:

aim_memory_store({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["Met at conference"]
  }]
})

To keep a topic separate, pass a context and the server creates memory-work.jsonl on demand:

aim_memory_store({
  context: "work",
  entities: [{
    name: "Q4_Project",
    entityType: "project",
    observations: ["Due December 2024"]
  }]
})

To force a location rather than relying on auto-detection, the location parameter takes project or global:

aim_memory_store({
  location: "global",
  entities: [{
    name: "Important_Info",
    entityType: "reference",
    observations: ["Stored in global master database"]
  }]
})

Reading back is a separate call. aim_memory_get takes an exact name, aim_memory_search takes a keyword, and aim_memory_list_stores reports what exists in both the project and global locations, with default listed for each.

Eleven tools, and what they do not cover

The tool surface is CRUD plus search. aim_memory_store creates entities, aim_memory_add_facts appends observations, aim_memory_link connects two memories, and the reverse operations are aim_memory_remove_facts, aim_memory_unlink and aim_memory_forget. Reading is split between aim_memory_search (keyword), aim_memory_get (exact name) and aim_memory_read_all (everything in one database). aim_memory_list_stores enumerates databases.

The limitation is visible in that list. Search is keyword-based, so there is no traversal query, no path finding between two entities and no way to ask for everything within two hops of a node. Relations exist as links, but the README does not describe a tool that walks them, which means graph structure is mostly something the model reconstructs after reading records. If your use case is "find every person connected to this project through any chain of links", this server does not offer that as a single call.

Concurrency is the other gap. The store is a JSONL file appended to by a single MCP server process. The README does not document locking, and it does not describe what happens when two clients, say Claude Desktop and a second editor, both point at the same --memory-path. The Dropbox example makes this concrete: two machines writing to one synced file is a scenario the documentation does not address. Treat one writer per file as the safe assumption until you have read the source.

Where a different tool is the better fit

If you need shared, queryable memory across a team or a service, a graph database backed by a server is the more honest choice. Neo4j is the obvious comparison: it stores a property graph, speaks Cypher, supports indexes and handles concurrent clients through a server process. The difference in approach is not cosmetic. mcp-knowledge-graph keeps the graph in a flat append-only file that any text tool can read; Neo4j keeps it in a database engine that answers traversal queries and enforces transactions. You trade query power and multi-writer safety for inspectability and zero infrastructure.

Within the MCP memory space itself, the model context protocol ecosystem has other memory servers, and the search data around this project shows people comparing several by name. The useful question is not which is best but which storage model you can live with. A file you can cat, grep and commit is a real operational advantage for a single developer. It stops being an advantage the moment a second process needs to write to the same file at the same time.

Maintenance, licence and the upgrade path

The repository is not archived, and the last push was on 2026-05-29. The most recent release listed is v1.3.2 from 2025-12-22, while package.json already declares version 1.4.0, so the published npm version and the tagged releases are not in lockstep and you should check which one npx resolves before relying on a specific behaviour.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the plain reading of the licence text; it is not legal advice, and if you redistribute the server inside a product you should read the LICENSE file in the repository yourself rather than take this summary as sufficient.

Upgrade cost is low but not zero. Because the bin is dist/index.js and the package ships only the dist folder, the client launches whatever npx pulls, so an unpinned npx -y mcp-knowledge-graph will silently move you to a newer build on the next start. Pinning the version in your args is the way to freeze it. The data files are plain JSONL, so an upgrade does not migrate anything, but it also means a future format change would have to be handled by the server, and the README does not describe a migration path.

Editorial conclusion

Adopt it if you want Claude or another MCP client to remember entities and relations across sessions and you are comfortable with the memory living in plain JSONL files you can read and edit yourself. Skip it if you need concurrent writers, a query language or a hosted memory service shared by a team. Before installing, check that Node is at least 22.0.0, decide whether the store belongs in .aim inside the project or in a global directory, and confirm that every file the server touches already starts with the {"type":"_aim"} marker line, because the server refuses to write to files without it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. shaneholloman/mcp-knowledge-graph on GitHub