{"id":30195771,"url":"https://github.com/tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp","last_synced_at":"2026-05-04T13:35:09.510Z","repository":{"id":309495212,"uuid":"1036459177","full_name":"tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp","owner":"tristan-mcinnis","description":"This guide provides complete instructions for implementing an **Agentic Semantic Memory System** that enables Claude agents to:","archived":false,"fork":false,"pushed_at":"2025-08-12T15:41:08.000Z","size":25,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-10T13:34:38.120Z","etag":null,"topics":["ai","claude","claude-code","llm","mcp","mcp-server","memory","neon-postgres","neondb","postgresql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tristan-mcinnis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T05:36:47.000Z","updated_at":"2025-10-07T10:30:44.000Z","dependencies_parsed_at":"2025-08-12T08:30:50.424Z","dependency_job_id":"ecd21122-acc6-4e44-b0de-89a4e77852f3","html_url":"https://github.com/tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp","commit_stats":null,"previous_names":["tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tristan-mcinnis","download_url":"https://codeload.github.com/tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32609919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: 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":["ai","claude","claude-code","llm","mcp","mcp-server","memory","neon-postgres","neondb","postgresql"],"created_at":"2025-08-13T05:00:36.136Z","updated_at":"2026-05-04T13:35:09.487Z","avatar_url":"https://github.com/tristan-mcinnis.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Agentic Semantic Memory System (MCP)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP Version](https://img.shields.io/badge/MCP-v0.6.2-blue)](https://github.com/anthropics/model-context-protocol)\n[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-green)](https://nodejs.org)\n\nA sophisticated Model Context Protocol (MCP) server that provides Claude Code with persistent semantic memory capabilities, enabling long-term information storage and retrieval across sessions. This system allows Claude to remember context, preferences, and important information between conversations.\n\n## 🌟 Key Features\n\n- **🧠 Persistent Memory**: Information survives across Claude Code sessions\n- **🔍 Semantic Search**: Retrieve memories based on meaning, not just keywords  \n- **📁 Project Namespaces**: Organize memories into separate contexts/projects\n- **🌐 Local Embeddings**: Works offline without external API dependencies\n- **🔗 Memory Relations**: Create knowledge graphs with connected memories\n- **🚀 Intent-Based Activation**: Natural language triggers automatic tool invocation\n- **📊 Full CRUD Operations**: Create, read, update, and delete memories\n- **🔐 Privacy-First**: All data stored in your own PostgreSQL database\n\n## 🏗️ Architecture\n\n### Core Components\n\n```\nagentic-memory/\n├── src/\n│   ├── index.ts           # MCP server entry point\n│   ├── db/\n│   │   ├── client.ts      # Database connection (Neon PostgreSQL)\n│   │   └── schema.ts      # Drizzle ORM schema (memories, relations)\n│   └── tools/\n│       ├── createMemory.ts    # Store new memories\n│       ├── searchMemory.ts    # Semantic search\n│       ├── listMemories.ts    # List and filter memories\n│       ├── deleteMemory.ts    # Remove memories\n│       ├── updateMemory.ts    # Modify existing memories\n│       ├── manageProjects.ts  # Project namespace management\n│       └── simpleEmbedding.ts # Local embedding generation\n├── run-server.sh          # Server startup script\n└── .env                   # Environment configuration\n```\n\n### How It Works\n\n1. **Claude Code** sends requests to the MCP server via stdio\n2. **MCP Server** processes tool requests (create, search, delete memories)\n3. **Embeddings** are generated locally using mathematical algorithms\n4. **PostgreSQL** (Neon) stores memories with pgvector for semantic search\n5. **Drizzle ORM** manages database operations and migrations\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ \n- PostgreSQL database with pgvector extension (Neon recommended)\n- Claude Code CLI installed\n\n### Installation\n\n1. **Clone or copy this MCP server to your project:**\n```bash\ncp -r /path/to/agentic-memory /your/project/.claude/mcp-servers/\n```\n\n2. **Install dependencies:**\n```bash\ncd /your/project/.claude/mcp-servers/agentic-memory\nnpm install\n```\n\n3. **Configure environment variables:**\n```bash\ncp .env.example .env\n# Edit .env with your database URL\n```\n\n4. **Run database migrations:**\n```bash\nnpm run db:migrate\n```\n\n5. **Add to Claude Code:**\n```bash\nclaude mcp add agentic-memory ./run-server.sh\n```\n\n6. **Verify connection:**\n```bash\nclaude mcp list\n# Should show: agentic-memory - ✓ Connected\n```\n\n## 📖 Usage\n\n### Available MCP Tools\n\n| Tool | Description | Example Use |\n|------|-------------|-------------|\n| `create_memory` | Store new information | \"Remember that the user prefers TypeScript\" |\n| `search_memory` | Find relevant memories | \"What do we know about the user's preferences?\" |\n| `list_memories` | View all memories | \"Show all memories in current project\" |\n| `delete_memory` | Remove specific memory | \"Delete memory with ID xyz\" |\n| `update_memory` | Modify existing memory | \"Update the location information\" |\n| `switch_project` | Change memory namespace | \"Switch to project 'work'\" |\n| `list_projects` | Show all projects | \"What projects exist?\" |\n| `delete_project` | Remove entire project | \"Delete the 'test' project\" |\n\n### Using with CLAUDE.md Orchestration\n\nThe `CLAUDE.md` file acts as a quasi-orchestrator, providing:\n- **Context Instructions**: High-level rules for memory usage\n- **Specialist Agents**: Memory agents that Claude Code can invoke\n- **Immutability Principles**: Memories should be append-only\n- **Quality Guidelines**: Only store high-signal, reusable information\n\nExample CLAUDE.md pattern:\n```markdown\n# Project Context: [Your Project Name]\n\nThis project uses an advanced semantic memory system to learn and improve over time.\n\n## Key Capabilities\n- **Semantic Memory**: Long-term memory storage and retrieval\n- **Specialist Agents**: Dedicated agents for memory operations\n\n## Core Principles\n- **Immutable Memories**: Once created, memories should not be altered\n- **High-Signal Only**: Store only reusable, non-obvious information\n- **No Secrets**: Never store API keys, passwords, or PII\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate `.env` file:\n```env\n# PostgreSQL connection (required)\nDATABASE_URL=postgresql://user:pass@host/db?sslmode=require\n\n# Optional: Embedding configuration\nEMBEDDING_MODEL=simple  # or 'llama' for advanced\nEMBEDDING_DIMENSIONS=1536\n\n# Optional: Default project\nDEFAULT_PROJECT=default\n```\n\n### Database Schema\n\nThe system uses two main tables:\n- `memories`: Stores content, embeddings, metadata, and timestamps\n- `memory_relations`: Links related memories (parent-child relationships)\n\n## 🧠 Embedding Systems\n\n### Simple Embeddings (Default)\n- **Pros**: No external dependencies, works offline, fast\n- **Cons**: Less semantic accuracy\n- **Use Case**: Development, restricted networks, testing\n\n### Llama CPP Embeddings (Advanced)\n- **Pros**: Higher semantic accuracy\n- **Cons**: Requires model download, more resources\n- **Use Case**: Production environments with good connectivity\n\n## 🎭 Agent Architecture\n\n### Current Agents\n✅ **Memory CRUD Agents**: Create, read, update, delete operations\n✅ **Project Management Agents**: Namespace organization\n✅ **Search Agent**: Semantic similarity search\n\n### Recommended Additional Agents\n\n1. **Memory Relations Agent**\n   - Create parent-child relationships\n   - Build knowledge graphs\n   - Track memory evolution\n\n2. **Memory Analytics Agent**\n   - Usage statistics\n   - Memory patterns\n   - Optimization recommendations\n\n3. **Export/Import Agent**\n   - Backup memories\n   - Transfer between projects\n   - Migration tools\n\n4. **Deduplication Agent**\n   - Detect similar memories\n   - Merge duplicates\n   - Maintain consistency\n\n## 🚨 Common Issues \u0026 Solutions\n\n### Issue: \"Failed to connect\" in MCP list\n**Solution**: Check `.env` file exists and DATABASE_URL is correct\n\n### Issue: Embedding dimension mismatch\n**Solution**: Ensure EMBEDDING_DIMENSIONS matches your database vector size\n\n### Issue: Memories not persisting across sessions\n**Solution**: Verify database connection and that migrations have run\n\n## 📝 Development\n\n### Running TypeScript directly:\n```bash\nnpm run dev\n```\n\n### Building for production:\n```bash\nnpm run build\n```\n\n### Running tests:\n```bash\nnpm test\n```\n\n## 🔄 Replication Guide\n\nTo replicate this setup in another codebase:\n\n1. **Copy the MCP server directory**\n2. **Set up a PostgreSQL database with pgvector**\n3. **Configure environment variables**\n4. **Run migrations**\n5. **Add to Claude Code configuration**\n6. **Create a CLAUDE.md file with memory instructions**\n7. **Test with simple memory operations**\n\n## 📊 Production Considerations\n\n- **Database Scaling**: Consider connection pooling for heavy usage\n- **Embedding Cache**: Implement caching for frequently accessed memories\n- **Backup Strategy**: Regular database backups are essential\n- **Security**: Never store sensitive information in memories\n- **Monitoring**: Track memory usage and search performance\n\n## 🤝 Contributing\n\nThis is a custom MCP implementation. To contribute:\n1. Improve embedding algorithms\n2. Add new memory management tools\n3. Enhance search capabilities\n4. Optimize database queries\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Areas for Contribution\n- Improve embedding algorithms\n- Add new memory management tools\n- Enhance search capabilities\n- Create visualization tools\n- Optimize database queries\n- Add support for more embedding models\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Anthropic](https://anthropic.com) for Claude and the MCP protocol\n- [Neon](https://neon.tech) for serverless PostgreSQL\n- [Drizzle ORM](https://orm.drizzle.team) for database management\n- The Claude Code community for feedback and suggestions\n\n## 📧 Contact\n\n**Tristan McInnis**\n- GitHub: [@tristan-mcinnis](https://github.com/tristan-mcinnis)\n- Project: [claude-code-agentic-semantic-memory-system-mcp](https://github.com/tristan-mcinnis/claude-code-agentic-semantic-memory-system-mcp)\n\n---\n\n**Built for Claude Code** - Enabling persistent, semantic memory across AI coding sessions.\n\n⭐ If you find this project useful, please consider giving it a star on GitHub!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftristan-mcinnis%2Fclaude-code-agentic-semantic-memory-system-mcp/lists"}