Server facts
MCP Knowledge Graph
Project
- Author
- shaneholloman
- License
- MIT
- Category
- Memory & Knowledge
Tech
- Runtime / language
- nodeTypeScript
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 885
- Last commit
- Data as of
Tags
- Entities
- Knowledge Graph
- Local Storage
- Persistent Memory
- Project Context
Overview
MCP Knowledge Graph gives assistants persistent memory built from entities, relationships, and observations. A memory can represent a person, project, or concept, while links connect those records and facts extend their descriptions. Tools support creating, retrieving, searching, and removing this information across conversations. The README presents the system for Claude Code, Claude Desktop, and other MCP-compatible platforms rather than tying the storage format to one assistant application.
Storage is local and file-based. The default database lives in memory.jsonl, while optional contexts create separate topic files. Location selection prioritizes a project's .aim directory over the configured global directory. A location parameter can override that automatic choice, and a discovery tool lists stores in both locations. The exact .aim directory name matters for project detection, whereas global storage can use a directory of the user's choosing, including a synced folder.
Each memory file starts with an identifying safety marker, and the server refuses writes to files without it. This is intended to avoid overwriting unrelated JSONL data. Search is described as case-insensitive keyword matching across memory names, types, and observations; exact-name retrieval is a separate operation. Setup uses npx with an explicit memory path and requires Node.js 22 or newer. The troubleshooting guidance notes that assistants may create similarly named topic databases, so consistent context naming remains useful even with automatic database creation.
Install & configure
Requirements
- Node.js 22 or newer
- An MCP-compatible AI platform
npx -y mcp-knowledge-graph --memory-path /Users/yourusername/.aimReplace the sample global memory path with your chosen directory. A project-root directory named exactly .aim takes priority when detected. Named contexts create additional JSONL databases automatically.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-knowledge-graph": {
"command": "npx",
"args": [
"-y",
"mcp-knowledge-graph",
"--memory-path",
"/Users/yourusername/.aim"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-knowledge-graph": {
"command": "npx",
"args": [
"-y",
"mcp-knowledge-graph",
"--memory-path",
"/Users/yourusername/.aim"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"mcp-knowledge-graph": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-knowledge-graph",
"--memory-path",
"/Users/yourusername/.aim"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-knowledge-graph": {
"command": "npx",
"args": [
"-y",
"mcp-knowledge-graph",
"--memory-path",
"/Users/yourusername/.aim"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-knowledge-graph": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-knowledge-graph",
"--memory-path",
"/Users/yourusername/.aim"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository tool metadata. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| aim_memory_store | Create persistent records for people, projects, concepts, or other entities. |
| aim_memory_link | Connect stored entities using a named directional relationship. |
| aim_memory_add_facts | Append observations to an existing entity while ignoring duplicates. |
| aim_memory_forget | Delete entities together with their associated relationships. |
| aim_memory_remove_facts | Remove selected observations without deleting their entity. |
| aim_memory_unlink | Remove relationships while preserving the linked entities. |
| aim_memory_read_all | Read a database's complete graph as structured JSON or readable text. |
| aim_memory_search | Match keywords against entity names, types, and observations without case sensitivity. |
| aim_memory_get | Retrieve entities by exact name and include relationships between the selected records. |
| aim_memory_list_stores | Discover project and global databases and report the current storage location. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Remember project facts and relationships between assistant sessions.
- Separate work and personal memories using named databases.
- Keep repository-specific memory in a project's .aim directory.
- Look up known entities or search observations by keyword.
Strengths
- Models relationships as well as individual facts.
- Supports project-local and global storage with explicit overrides.
- Uses file markers to guard against unrelated JSONL overwrites.
- Provides discovery of available memory stores.
Limitations
- Requires Node.js 22 or newer.
- Project detection depends on the exact .aim directory name.
- Inconsistent context naming can create redundant databases.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
