Skip to content
Back to search

mcp-knowledge-graph

MCP server enabling persistent memory for Claude through a local knowledge graph - fork focused on local development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shaneholloman--mcp-knowledge-graph/badge.svg)](/listings/shaneholloman--mcp-knowledge-graph)

HTML

<a href="/listings/shaneholloman--mcp-knowledge-graph"><img src="/api/listings/shaneholloman--mcp-knowledge-graph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Global Memory (Recommended)

Add to your `claude_desktop_config.json` or `.claude.json`. Two common approaches:

**Option 1: Default `.aim` directory (simple)**

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

**Option 2: Dropbox/cloud sync (portable)**

For accessing memories across multiple machines, use a synced folder. This is how the author of this MCP server keeps his own memories:

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

This creates memory files in your specified directory:

- `memory.jsonl` - **Master Database** (default for all operations) - `memory-work.jsonl` - Work database - `memory-personal.jsonl` - Personal database - etc.

Project-Local Memory

In any project, create a `.aim` directory:

mkdir .aim

Now memory tools automatically use `.aim/memory.jsonl` (project-local **master database**) instead of global storage when run from this project.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 298 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Knowledge Graph
  2. **Persistent memory for AI models through a local knowledge graph.**
  3. Store and retrieve information across conversations using entities, relations, and observations. Works with Claude Code/Desktop and any MCP-compatible AI platform.
  4. ## Why ".aim" and "aim_" prefixes?
  5. AIM stands for **AI Memory** - the core concept of this system. The three AIM elements provide clear organization and safety:
  6. - **`.aim` directories**: Keep AI memory files organized and easily identifiable
  7. - **`aim_` tool prefixes**: Group related memory functions together in multi-tool setups
  8. - **`_aim` safety markers**: Each memory file starts with `{"type":"_aim","source":"mcp-knowledge-graph"}` to prevent accidental overwrites of unrelated JSONL files
  9. This consistent AIM naming makes it obvious which directories, tools, and files belong to the AI memory system.
  10. ## CRITICAL: Understanding `.aim` dir vs `_aim` file marker
  11. **Two different things with similar names:**
  12. - `.aim` = **Project-local directory name** (MUST be named exactly `.aim` for project detection to work)
  13. - `_aim` = **File safety marker** (appears inside JSONL files: `{"type":"_aim","source":"mcp-knowledge-graph"}`)
  14. **For project-local storage:**
  15. - Directory MUST be named `.aim` in your project root
  16. - Example: `my-project/.aim/memory.jsonl`
  17. - The system specifically looks for this exact name
  18. **For global storage (--memory-path):**
  19. - Can be ANY directory you want
  20. - Examples: `~/yourusername/.aim/`, `~/memories/`, `~/Dropbox/ai-memory/`, `~/Documents/ai-data/`
  21. - Complete flexibility - choose whatever location works for you
  22. ## Storage Logic
  23. **File Location Priority:**
  24. 1. **Project with `.aim`** - Uses `.aim/memory.jsonl` (project-local)
  25. 2. **No project/no .aim** - Uses configured global directory
  26. 3. **Contexts** - Adds suffix: `memory-work.jsonl`, `memory-personal.jsonl`
  27. **Safety System:**
  28. - Every memory file starts with `{"type":"_aim","source":"mcp-knowledge-graph"}`
  29. - System refuses to write to files without this marker
  30. - Prevents accidental overwrite of unrelated JSONL files
  31. ## Master Database Concept
  32. **The master database is your primary memory store** - used by default when no specific database is requested. It's always named `default` in listings and stored as `memory.jsonl`.
  33. - **Default Behavior**: All memory operations use the master database unless you specify a different one
  34. - **Always Available**: Exists in both project-local and global locations
  35. - **Primary Storage**: Your main knowledge graph that persists across all conversations
  36. - **Named Databases**: Optional additional databases (`work`, `personal`, `health`) for organizing specific topics
  37. ## Key Features
  38. - **Master Database**: Primary memory store used by default for all operations
  39. - **Multiple Databases**: Optional named databases for organizing memories by topic
  40. - **Project Detection**: Automatic project-local memory using `.aim` directories
  41. - **Location Override**: Force operations to use project or global storage
  42. - **Safe Operations**: Built-in protection against overwriting unrelated files
  43. - **Database Discovery**: List all available databases in both locations
  44. ## Quick Start
  45. ### Global Memory (Recommended)
  46. Add to your `claude_desktop_config.json` or `.claude.json`. Two common approaches:
  47. **Option 1: Default `.aim` directory (simple)**
  48. ```json
  49. {
  50. "mcpServers": {
  51. "Aim-Memory-Bank": {
  52. "command": "npx",
  53. "args": [
  54. "-y",
  55. "mcp-knowledge-graph",
  56. "--memory-path",
  57. "/Users/yourusername/.aim"
  58. ]
  59. }
  60. }
  61. }
  62. ```
  63. **Option 2: Dropbox/cloud sync (portable)**
  64. For accessing memories across multiple machines, use a synced folder. This is how the author of this MCP server keeps his own memories:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "Aim-Memory-Bank": {
  69. "command": "npx",
  70. "args": [
  71. "-y",
  72. "mcp-knowledge-graph",
  73. "--memory-path",
  74. "/Users/yourusername/Dropbox/ai-memory"
  75. ]
  76. }
  77. }
  78. }
  79. ```
  80. This creates memory files in your specified directory:
  81. - `memory.jsonl` - **Master Database** (default for all operations)
  82. - `memory-work.jsonl` - Work database
  83. - `memory-personal.jsonl` - Personal database
  84. - etc.
  85. ### Project-Local Memory
  86. In any project, create a `.aim` directory:
  87. ```bash
  88. mkdir .aim
  89. ```
  90. Now memory tools automatically use `.aim/memory.jsonl` (project-local **master database**) instead of global storage when run from this project.
  91. ## How AI Uses Databases
  92. Once configured, AI models use the **master database by default** or can specify named databases with a `context` parameter. New databases are created automatically - no setup required:
  93. ```json
  94. // Master Database (default - no context needed)
  95. aim_memory_store({
  96. entities: [{
  97. name: "John_Doe",
  98. entityType: "person",
  99. observations: ["Met at conference"]
  100. }]
  101. })
  102. // Work database
  103. aim_memory_store({
  104. context: "work",
  105. entities: [{
  106. name: "Q4_Project",
  107. entityType: "project",
  108. observations: ["Due December 2024"]
  109. }]
  110. })
  111. // Personal database
  112. aim_memory_store({
  113. context: "personal",
  114. entities: [{
  115. name: "Mom",
  116. entityType: "person",
  117. observations: ["Birthday March 15th"]
  118. }]
  119. })
  120. // Master database in specific location
  121. aim_memory_store({
  122. location: "global",
  123. entities: [{
  124. name: "Important_Info",
  125. entityType: "reference",
  126. observations: ["Stored in global master database"]
  127. }]
  128. })
  129. ```
  130. ## File Organization
  131. **Global Setup:**
  132. ```tree
  133. /Users/yourusername/.aim/
  134. ├── memory.jsonl # Master Database (default)
  135. ├── memory-work.jsonl # Work database
  136. ├── memory-personal.jsonl # Personal database
  137. └── memory-health.jsonl # Health database
  138. ```
  139. **Project Setup:**
  140. ```tree
  141. my-project/
  142. ├── .aim/
  143. │ ├── memory.jsonl # Project Master Database (default)
  144. │ └── memory-work.jsonl # Project Work database
  145. └── src/
  146. ```
  147. ## Available Tools
  148. - `aim_memory_store` - Store new memories (people, projects, concepts)
  149. - `aim_memory_add_facts` - Add facts to existing memories
  150. - `aim_memory_link` - Link two memories together
  151. - `aim_memory_search` - Search memories by keyword
  152. - `aim_memory_get` - Retrieve specific memories by exact name
  153. - `aim_memory_read_all` - Read all memories in a database
  154. - `aim_memory_list_stores` - List available databases
  155. - `aim_memory_forget` - Forget memories
  156. - `aim_memory_remove_facts` - Remove specific facts from a memory
  157. - `aim_memory_unlink` - Remove links between memories
  158. ### Parameters
  159. - `context` (optional) - Specify named database (`work`, `personal`, etc.). Defaults to **master database**
  160. - `location` (optional) - Force `project` or `global` storage location. Defaults to auto-detection
  161. ## Database Discovery
  162. Use `aim_memory_list_stores` to see all available databases:
  163. ```json
  164. {
  165. "project_databases": [
  166. "default", // Master Database (project-local)
  167. "project-work" // Named database
  168. ],
  169. "global_databases": [
  170. "default", // Master Database (global)
  171. "work",
  172. "personal",
  173. "health"
  174. ],
  175. "current_location": "project (.aim directory detected)"
  176. }
  177. ```
  178. **Key Points:**
  179. - **"default"** = Master Database in both locations
  180. - **Current location** shows whether you're using project or global storage
  181. - **Master database exists everywhere** - it's your primary memory store
  182. - **Named databases** are optional additions for specific topics
  183. ## Configuration Examples
  184. **Important:** Always specify `--memory-path` to control where your memory files are stored.
  185. **Auto-approve read operations (recommended):**
  186. ```json
  187. {
  188. "mcpServers": {
  189. "Aim-Memory-Bank": {
  190. "command": "npx",
  191. "args": [
  192. "-y",
  193. "mcp-knowledge-graph",
  194. "--memory-path",
  195. "/Users/yourusername/.aim"
  196. ],
  197. "autoapprove": [
  198. "aim_memory_search",
  199. "aim_memory_get",
  200. "aim_memory_read_all",
  201. "aim_memory_list_stores"
  202. ]
  203. }
  204. }
  205. }
  206. ```
  207. ## Troubleshooting
  208. **"File does not contain required _aim safety marker" error:**
  209. - The file may not belong to this system
  210. - Manual JSONL files need `{"type":"_aim","source":"mcp-knowledge-graph"}` as first line
  211. - If you created the file manually, add the `_aim` marker or delete and let the system recreate it
  212. **Memories going to unexpected locations:**
  213. - Check if you're in a project directory with `.aim` folder (uses project-local storage)
  214. - Otherwise uses the configured global `--memory-path` directory
  215. - Use `aim_memory_list_stores` to see all available databases and current location
  216. - Use `ls .aim/` or `ls /Users/yourusername/.aim/` to see your memory files
  217. **Too many similar databases:**
  218. - AI models try to use consistent names, but may create variations
  219. - Manually delete unwanted database files if needed
  220. - Encourage AI to use simple, consistent database names
  221. - **Remember**: Master database is always available as the default - named databases are optional
  222. ## Requirements
  223. - Node.js 22+
  224. - MCP-compatible AI platform
  225. ## License
  226. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.