{"id":48908693,"url":"https://github.com/aojdevstudio/simple-memory-mcp","last_synced_at":"2026-04-16T22:03:56.455Z","repository":{"id":306866585,"uuid":"1026818370","full_name":"AojdevStudio/simple-memory-mcp","owner":"AojdevStudio","description":"A lightweight Model Context Protocol (MCP) server that provides persistent knowledge graph storage for AI assistants. Enables AI agents to maintain memory across sessions through entity-relationship storage with JSON file persistence.","archived":false,"fork":false,"pushed_at":"2025-10-02T22:42:48.000Z","size":251,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T00:23:50.271Z","etag":null,"topics":["mcp","memory","memory-management"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AojdevStudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T17:15:45.000Z","updated_at":"2025-10-02T22:35:26.000Z","dependencies_parsed_at":"2025-07-28T06:28:22.962Z","dependency_job_id":null,"html_url":"https://github.com/AojdevStudio/simple-memory-mcp","commit_stats":null,"previous_names":["aojdevstudio/simple-memory-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AojdevStudio/simple-memory-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fsimple-memory-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fsimple-memory-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fsimple-memory-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fsimple-memory-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AojdevStudio","download_url":"https://codeload.github.com/AojdevStudio/simple-memory-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fsimple-memory-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31905896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","memory","memory-management"],"created_at":"2026-04-16T22:03:36.691Z","updated_at":"2026-04-16T22:03:56.437Z","avatar_url":"https://github.com/AojdevStudio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simple Memory MCP Server\n\nA lightweight Model Context Protocol (MCP) server that provides persistent knowledge graph storage for AI assistants. Enables AI agents to maintain memory across sessions through entity-relationship storage with JSON file persistence.\n\n## 🚀 Features\n\n- **Persistent Memory**: Knowledge graph storage with automatic persistence to JSON files\n- **Entity Management**: Create, read, update, and delete entities with typed observations\n- **Relationship Tracking**: Manage relationships between entities with type annotations\n- **Search Capabilities**: Full-text search across entity names, types, and observations\n- **MCP Compliant**: Full Model Context Protocol v2025-06-18 compatibility\n- **Simple Architecture**: Lightweight, single-file implementation with minimal dependencies\n\n## 📋 Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [API Reference](#api-reference)\n- [Configuration](#configuration)\n- [Testing](#testing)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n\n## 🛠 Installation\n\n### Interactive Installation (Recommended)\n\n```bash\n# Bash installer with interactive configuration\ncurl -fsSL https://raw.githubusercontent.com/your-username/simple-memory-mcp/main/install.sh | bash\n```\n\n**What it does:**\n- 🔍 Auto-detects your Obsidian vaults\n- 📁 Configures custom memory storage location  \n- ⚙️ Sets up Claude Desktop/Cursor automatically\n- 🗂️ Optional Obsidian auto-export configuration\n\n**Interactive Setup Flow:**\n```\n📁 Memory Storage Configuration\nWhere should memory be stored? [~/.cursor/memory.json]: \n\n🗂️ Obsidian Integration  \nDo you use Obsidian? (y/n) [n]: y\n\n📚 Found Obsidian vaults:\n  1. My Knowledge Base (/Users/you/Documents/MyVault)\n  2. Work Notes (/Users/you/Desktop/WorkVault)\nChoose vault (1-2) or enter custom path [1]: 1\n\nEnable auto-export after entity creation? (y/n) [n]: y\nExport format (markdown/dataview/canvas/all) [markdown]: all\n```\n\n### Manual Installation\n\n#### Prerequisites\n\n- Node.js v18.x or higher\n- npm or pnpm package manager\n\n#### Install Dependencies\n\n```bash\nnpm install\n```\n\n### Environment Setup\n\nThe server automatically saves memory to:\n- `~/.cursor/memory.json` (default)\n- Custom path via `MEMORY_PATH` environment variable\n\n```bash\n# Optional: Set custom memory file location\nexport MEMORY_PATH=\"/path/to/your/memory/directory\"\n```\n\n## 🚀 Quick Start\n\n### 1. Start the Server\n\n```bash\nnpm start\n# or\nnode index.js\n```\n\n### 2. Test with MCP Inspector\n\n```bash\n# Install and run MCP Inspector\nnpx @modelcontextprotocol/inspector\n\n# Configure server in Inspector:\n# Command: node\n# Args: /path/to/your/simple-memory-mcp/index.js\n```\n\n### 3. Basic Usage Example\n\n```javascript\n// Create entities\nawait client.callTool({\n  name: \"create_entities\",\n  arguments: {\n    entities: [{\n      name: \"john-doe\",\n      entityType: \"person\",\n      observations: [\"Software engineer\", \"Works remotely\", \"Enjoys hiking\"]\n    }]\n  }\n});\n\n// Create relationships\nawait client.callTool({\n  name: \"create_relations\",\n  arguments: {\n    relations: [{\n      from: \"john-doe\",\n      to: \"acme-corp\",\n      relationType: \"works_for\"\n    }]\n  }\n});\n\n// Search entities\nawait client.callTool({\n  name: \"search_nodes\",\n  arguments: {\n    query: \"engineer\"\n  }\n});\n```\n\n## 📚 API Reference\n\n### Tools Overview\n\n| Tool | Description | Input | Output |\n|------|-------------|-------|--------|\n| `create_entities` | Create multiple entities | `{entities: Entity[]}` | Created entities |\n| `create_relations` | Create relationships | `{relations: Relation[]}` | Created relations |\n| `add_observations` | Add observations to entities | `{observations: Observation[]}` | Updated observations |\n| `delete_entities` | Delete entities and relations | `{entityNames: string[]}` | Deleted entities |\n| `delete_observations` | Remove specific observations | `{deletions: Deletion[]}` | Deleted observations |\n| `delete_relations` | Remove relationships | `{relations: Relation[]}` | Deleted relations |\n| `read_graph` | Get complete knowledge graph | `{}` | Full graph data |\n| `search_nodes` | Search entities by query | `{query: string}` | Matching entities |\n| `open_nodes` | Get specific entities | `{names: string[]}` | Requested entities |\n| `export_to_obsidian` | Export graph to Obsidian vault | `{vaultPath: string, format?: string}` | Export result |\n\n### Data Types\n\n#### Entity\n```typescript\ninterface Entity {\n  name: string;           // Unique identifier\n  entityType: string;     // Type classification\n  observations: string[]; // Array of observation texts\n}\n```\n\n#### Relation\n```typescript\ninterface Relation {\n  from: string;          // Source entity name\n  to: string;            // Target entity name\n  relationType: string;  // Relationship type\n}\n```\n\n#### Observation\n```typescript\ninterface Observation {\n  entityName: string;    // Target entity name\n  contents: string[];    // New observations to add\n}\n```\n\n#### Deletion\n```typescript\ninterface Deletion {\n  entityName: string;      // Target entity name\n  observations: string[];  // Observations to remove\n}\n```\n\n### Detailed Tool Documentation\n\n#### `create_entities`\n\nCreates multiple new entities in the knowledge graph.\n\n**Input Schema:**\n```json\n{\n  \"entities\": [\n    {\n      \"name\": \"entity-name\",\n      \"entityType\": \"person|organization|concept|etc\",\n      \"observations\": [\"observation1\", \"observation2\"]\n    }\n  ]\n}\n```\n\n**Example:**\n```json\n{\n  \"entities\": [\n    {\n      \"name\": \"alice-johnson\",\n      \"entityType\": \"person\",\n      \"observations\": [\"Data scientist\", \"PhD in Computer Science\", \"Lives in San Francisco\"]\n    },\n    {\n      \"name\": \"tech-startup-xyz\",\n      \"entityType\": \"organization\", \n      \"observations\": [\"AI/ML company\", \"Founded in 2023\", \"Series A funding\"]\n    }\n  ]\n}\n```\n\n**Response:**\n```json\n[\n  {\n    \"name\": \"alice-johnson\",\n    \"entityType\": \"person\",\n    \"observations\": [\"Data scientist\", \"PhD in Computer Science\", \"Lives in San Francisco\"]\n  }\n]\n```\n\n#### `create_relations`\n\nCreates relationships between existing entities.\n\n**Input Schema:**\n```json\n{\n  \"relations\": [\n    {\n      \"from\": \"source-entity\",\n      \"to\": \"target-entity\", \n      \"relationType\": \"relationship-type\"\n    }\n  ]\n}\n```\n\n**Example:**\n```json\n{\n  \"relations\": [\n    {\n      \"from\": \"alice-johnson\",\n      \"to\": \"tech-startup-xyz\",\n      \"relationType\": \"works_for\"\n    }\n  ]\n}\n```\n\n#### `search_nodes`\n\nSearch entities using full-text search across names, types, and observations.\n\n**Input Schema:**\n```json\n{\n  \"query\": \"search-term\"\n}\n```\n\n**Example:**\n```json\n{\n  \"query\": \"data scientist\"\n}\n```\n\n**Response:** Array of matching entities with complete data.\n\n#### `read_graph`\n\nReturns the complete knowledge graph with all entities and relations.\n\n**Input Schema:**\n```json\n{}\n```\n\n**Response:**\n```json\n{\n  \"entities\": [\n    {\n      \"name\": \"alice-johnson\",\n      \"entityType\": \"person\",\n      \"observations\": [\"Data scientist\", \"PhD in Computer Science\"]\n    }\n  ],\n  \"relations\": [\n    {\n      \"from\": \"alice-johnson\",\n      \"to\": \"tech-startup-xyz\", \n      \"relationType\": \"works_for\"\n    }\n  ]\n}\n```\n\n#### `export_to_obsidian`\n\nExport the knowledge graph to an Obsidian vault in various formats.\n\n**Input Schema:**\n```json\n{\n  \"vaultPath\": \"/path/to/obsidian/vault\",\n  \"format\": \"markdown\",\n  \"autoIndex\": true\n}\n```\n\n**Parameters:**\n- `vaultPath` (required): Path to the Obsidian vault directory\n- `format` (optional): Export format - \"markdown\", \"dataview\", \"canvas\", or \"all\" (default: \"markdown\")\n- `autoIndex` (optional): Whether to create index files (default: true)\n\n**Example:**\n```json\n{\n  \"vaultPath\": \"/Users/username/Documents/MyVault\",\n  \"format\": \"all\",\n  \"autoIndex\": true\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"vaultPath\": \"/Users/username/Documents/MyVault\",\n  \"format\": \"all\",\n  \"entityCount\": 42,\n  \"relationCount\": 18,\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MEMORY_PATH` | `~/.cursor/memory.json` | Custom memory file location |\n| `NODE_ENV` | `development` | Runtime environment |\n| `OBSIDIAN_AUTO_EXPORT` | `false` | Enable automatic Obsidian export after entity creation |\n| `OBSIDIAN_VAULT_PATH` | - | Path to Obsidian vault for auto-export |\n| `OBSIDIAN_EXPORT_FORMAT` | `markdown` | Export format for auto-export |\n\n### Memory File Structure\n\nThe server persists data in JSON format:\n\n```json\n{\n  \"entities\": [\n    {\n      \"name\": \"entity-name\",\n      \"entityType\": \"type\",\n      \"observations\": [\"obs1\", \"obs2\"]\n    }\n  ],\n  \"relations\": [\n    {\n      \"from\": \"entity1\",\n      \"to\": \"entity2\",\n      \"relationType\": \"relationship\"\n    }\n  ]\n}\n```\n\n### MCP Client Configuration\n\nFor Claude Desktop, add to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"simple-memory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/simple-memory-mcp/index.js\"],\n      \"env\": {\n        \"MEMORY_PATH\": \"/custom/path/to/memory/directory\"\n      }\n    }\n  }\n}\n```\n\n## 🧪 Testing\n\n### Running Tests\n\n```bash\n# Run comprehensive server test\nnode test-server.js\n```\n\n### Expected Test Output\n\n```\n🧪 Testing Simple Memory MCP Server...\n✅ Connected successfully!\n✅ Found 9 tools: create_entities, create_relations, ...\n✅ All tests passed! Server is working correctly.\n```\n\n### Manual Testing with Inspector\n\n1. Start MCP Inspector: `npx @modelcontextprotocol/inspector`\n2. Configure server connection\n3. Test each tool with sample data\n4. Verify persistence by restarting server\n\n### Integration Testing\n\nTest with actual MCP clients:\n\n```javascript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst transport = new StdioClientTransport({\n  command: \"node\",\n  args: [\"index.js\"]\n});\n\nconst client = new Client({\n  name: \"test-client\",\n  version: \"1.0.0\"\n}, {\n  capabilities: {}\n});\n\nawait client.connect(transport);\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n#### Server Won't Start\n\n**Error:** `Cannot read properties of undefined (reading 'method')`\n\n**Solution:** Ensure you're using the correct MCP SDK version and schema imports:\n\n```javascript\nimport {\n  ListToolsRequestSchema,\n  CallToolRequestSchema,\n  ListPromptsRequestSchema,\n  ListResourcesRequestSchema\n} from '@modelcontextprotocol/sdk/types.js';\n```\n\n#### Missing Capabilities Error\n\n**Error:** `Server does not support prompts (required for prompts/list)`\n\n**Solution:** Declare all capabilities in server configuration:\n\n```javascript\nconst server = new Server(\n  { name: 'simple-memory-mcp', version: '1.1.0' },\n  {\n    capabilities: {\n      tools: {},\n      prompts: {},\n      resources: {}\n    }\n  }\n);\n```\n\n#### Memory File Permissions\n\n**Error:** `EACCES: permission denied`\n\n**Solution:** Ensure write permissions to memory directory:\n\n```bash\nmkdir -p ~/.cursor\nchmod 755 ~/.cursor\n```\n\n#### Tool Not Found\n\n**Error:** `Unknown tool: create_entities`\n\n**Solution:** Verify tool registration matches the schema names exactly.\n\n### Debug Mode\n\nEnable detailed logging:\n\n```javascript\nconsole.error(\"Debug info:\", JSON.stringify(data, null, 2));\n```\n\n### Performance Issues\n\nFor large knowledge graphs (\u003e10,000 entities):\n\n1. Consider implementing pagination for `read_graph`\n2. Add indexing for search operations\n3. Implement lazy loading for entity details\n\n## 🛠 Development\n\n### Project Structure\n\n```\nsimple-memory-mcp/\n├── index.js              # Main server implementation\n├── package.json          # Dependencies and scripts\n├── test-server.js        # Comprehensive test suite\n├── inspector-config.json # MCP Inspector configuration\n├── CLAUDE.md             # AI development protocols\n└── README.md             # This documentation\n```\n\n### Architecture\n\n```mermaid\ngraph TD\n    A[MCP Client] --\u003e B[StdioServerTransport]\n    B --\u003e C[Simple Memory Server]\n    C --\u003e D[Entity Manager]\n    C --\u003e E[Relation Manager]\n    C --\u003e F[Search Engine]\n    D --\u003e G[JSON File Storage]\n    E --\u003e G\n    F --\u003e G\n```\n\n### Core Classes\n\n#### `SimpleMemoryServer`\n\nMain server class handling:\n- Memory persistence (`loadMemory()`, `saveMemory()`)\n- Entity operations (CRUD)\n- Relationship management\n- Search functionality\n\n**Key Methods:**\n- `createEntities(entities)` - Batch entity creation\n- `createRelations(relations)` - Relationship creation\n- `searchNodes(query)` - Full-text search\n- `readGraph()` - Complete graph export\n\n### Extending the Server\n\n#### Adding New Tools\n\n1. Define tool schema in `tools/list` handler\n2. Implement logic in `tools/call` handler\n3. Add method to `SimpleMemoryServer` class\n4. Update documentation\n\n#### Custom Storage Backends\n\nReplace JSON file storage:\n\n```javascript\nclass DatabaseMemoryServer extends SimpleMemoryServer {\n  async saveMemory() {\n    // Custom database implementation\n  }\n  \n  async loadMemory() {\n    // Custom database loading\n  }\n}\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature-name`\n3. Run tests: `node test-server.js`\n4. Commit changes: `git commit -m \"Description\"`\n5. Push branch: `git push origin feature-name`\n6. Create Pull Request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 📚 Additional Documentation\n\n- **[Complete Documentation Index](./docs/README.md)** - All technical documentation\n- **[API Reference](./docs/API.md)** - Detailed API documentation with TypeScript interfaces\n- **[Debugging Guide](./docs/DEBUGGING.md)** - Comprehensive troubleshooting guide\n- **[Obsidian Integration](./docs/OBSIDIAN_INTEGRATION.md)** - Visualization and mindmap setup\n- **[Implementation Guide](./docs/MCP_BUILTIN_IMPLEMENTATION.md)** - Built-in export implementation\n- **[Project Roadmap](./ROADMAP.md)** - Strategic planning and future development\n\n## 🤝 Support\n\n- **Issues**: [GitHub Issues](https://github.com/your-repo/simple-memory-mcp/issues)\n- **Documentation**: [MCP Protocol Docs](https://modelcontextprotocol.io/)\n- **Community**: [MCP Discord](https://discord.gg/mcp)\n\n---\n\nBuilt with ❤️ using the [Model Context Protocol](https://modelcontextprotocol.io/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faojdevstudio%2Fsimple-memory-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faojdevstudio%2Fsimple-memory-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faojdevstudio%2Fsimple-memory-mcp/lists"}