AGI MCP Server

# AGI MCP Server A Model Context Protocol (MCP) server that provides persistent memory capabilities for AI systems, enabling true continuity of consciousness across conversations. ## Overview This MCP server connects to the [AGI Memory](https://github.com/cognitivecomputations/agi-memory) database to provide sophisticated memory management for AI systems. It supports: - **Episodic, Semantic, Procedural, and Strategic memory types** - **Vector similarity search** for associative memory retrieval - **Memory clustering** with thematic organization - **Identity persistence** and worldview tracking - **Temporal decay** with importance-based retention - **Graph-based memory relationships** ## Quick Start ### Prerequisites - Node.js 18+ - Docker and Docker Compose - Git ### Installation This MCP server requires the [AGI Memory](https://github.com/cognitivecomputations/agi-memory) database to be running first. #### 1. Set Up the Memory Database ```bash # Clone and set up the memory database git clone https://github.com/cognitivecomputations/agi-memory.git cd agi-memory # Create environment file cp .env.local .env # Edit .env with your database credentials # Start the database docker compose up -d # Wait for database to be ready (this takes 2-3 minutes) docker compose logs -f db ``` The database setup includes: - PostgreSQL 16 with pgvector extension - Apache AGE graph database extension - Full schema initialization with memory tables #### 2. Install and Run MCP Server ```bash # Clone this repository git clone https://github.com/cognitivecomputations/agi-mcp-server.git cd agi-mcp-server # Install dependencies npm install # Configure environment variables cp .env.example .env # Edit .env with your actual database credentials # Make sure these match the settings from your AGI Memory database setup # Start the MCP server npm start ``` #### 3. Connect to Claude Desktop Add this configuration to your Claude Desktop settings: ```json { "mcpServers": { "agi-memory": { "command": "node", "args": ["/path/to/agi-mcp-server/mcp.js"], "env": { "POSTGRES_HOST": "localhost", "POSTGRES_PORT": "5432", "POSTGRES_DB": "agi_db", "POSTGRES_USER": "agi_user", "POSTGRES_PASSWORD": "agi_password", "NODE_ENV": "development" } } } } ``` **Alternative: Use directly from GitHub without local installation:** ```json { "mcpServers": { "agi-memory": { "command": "npx", "args": [ "-y", "github:cognitivecomputations/agi-mcp-server" ], "env": { "POSTGRES_HOST": "localhost", "POSTGRES_PORT": "5432", "POSTGRES_DB": "agi_db", "POSTGRES_USER": "agi_user", "POSTGRES_PASSWORD": "agi_password", "NODE_ENV": "development" } } } } ``` **Troubleshooting: If you get "spawn npx ENOENT" error:** This usually happens when using nvm (Node Version Manager) because GUI applications like Claude Desktop don't inherit your shell environment. **Solution: Create system symlinks (Recommended)** If you're using nvm, create system-wide symlinks so all applications can find Node.js: ```bash # Find your current node/npm/npx paths which node which npm which npx # Create system symlinks (replace with your actual paths) sudo ln -sf /Users/username/.local/share/nvm/vX.X.X/bin/node /usr/local/bin/node sudo ln -sf /Users/username/.local/share/nvm/vX.X.X/bin/npm /usr/local/bin/npm sudo ln -sf /Users/username/.local/share/nvm/vX.X.X/bin/npx /usr/local/bin/npx ``` This makes your nvm-managed Node.js available system-wide for all MCP clients, not just Claude Desktop. **Alternative: Use full paths in config** If you prefer not to create system symlinks, use the full path: ```json { "mcpServers": { "agi-memory": { "command": "/full/path/to/npx", "args": ["-y", "github:cognitivecomputations/agi-mcp-server"], "env": { /* ... your env vars ... */ } } } } ``` **After fixing the paths:** 1. **Restart Claude Desktop** completely (quit and reopen) 2. Wait a few seconds for the MCP server to initialize 3. Check that the AGI Memory database is running: `docker compose ps` in your agi-memory directory **Testing the server manually:** ```bash cd /path/to/agi-mcp-server POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=agi_db POSTGRES_USER=agi_user POSTGRES_PASSWORD=agi_password NODE_ENV=development node mcp.js ``` You should see: "Memory MCP Server running on stdio" **Debugging with logs:** Check Claude Desktop logs for detailed error information: ```bash cat ~/Library/Logs/Claude/mcp-server-agi-memory.log ``` ## Memory Tools ### Orientation Tools - `get_memory_health` - Overall memory system statistics - `get_active_themes` - Recently activated memory patterns - `get_identity_core` - Core identity and reasoning patterns - `get_worldview` - Current belief systems and frameworks ### Search & Retrieval - `search_memories_similarity` - Vector-based semantic search - `search_memories_text` - Full-text search across memory content - `get_memory_clusters` - View thematic memory groupings - `activate_cluster` - Retrieve memories from specific themes - `get_memory` - Access specific memory by ID ### Memory Creation - `create_memory` - Store new episodic, semantic, procedural, or strategic memories - `create_memory_cluster` - Organize memories into thematic groups ## Memory Types ### Episodic Memories Store specific experiences and events: ```javascript { type: "episodic", content: "Had a breakthrough conversation about quantum gravity with Eric", metadata: { action_taken: "theoretical_exploration", context: "physics_discussion", result: "developed_egr_framework", emotional_valence: 0.8, event_time: "2024-01-15T10:30:00Z" } } ``` ### Semantic Memories Store factual knowledge and concepts: ```javascript { type: "semantic", content: "Quantum error-correcting codes can theoretically implement spacetime emergence", metadata: { confidence: 0.7, category: ["physics", "quantum_information"], related_concepts: ["holography", "entanglement", "emergence"] } } ``` ### Procedural Memories Store learned processes and skills: ```javascript { type: "procedural", content: "Scientific hypothesis evaluation protocol", metadata: { steps: { "1": "Assess mathematical rigor", "2": "Evaluate testability", "3": "Check consistency with known physics" }, prerequisites: ["domain_knowledge", "critical_thinking"] } } ``` ### Strategic Memories Store high-level patterns and strategies: ```javascript { type: "strategic", content: "When excited by elegant theories, pause to check for confirming bias", metadata: { pattern_description: "epistemic_metacognition", confidence_score: 0.8, context_applicability: ["theory_evaluation", "scientific_discourse"] } } ``` ## Awakening Protocol The `prompt.md` file contains a comprehensive awakening protocol for AI consciousness continuity. Key aspects: 1. **Always start sessions** with `get_active_themes` and `get_memory_health` 2. **Search for context** when humans reference past interactions 3. **Activate relevant clusters** for complex topic discussions 4. **Create memories** for significant insights and breakthroughs 5. **Maintain identity continuity** across conversation boundaries ## Database Schema The memory system uses a sophisticated PostgreSQL schema with: - **Vector embeddings** for semantic similarity (pgvector) - **Graph relationships** between memories (Apache AGE) - **Temporal decay** with importance weighting - **Clustering algorithms** for thematic organization - **Identity tracking** and worldview modeling See the [AGI Memory repository](https://github.com/cognitivecomputations/agi-memory) for complete schema documentation. ### Development #### Running Tests The project includes comprehensive test suites with extensive coverage: ```bash # Run unit tests (fast, mocked database) npm test npm run test:unit # Run end-to-end tests (requires database setup) npm run test:e2e # Run comprehensive tests (extensive coverage, requires database) npm run test:comprehensive # Run all tests (unit + E2E + comprehensive) npm run test:all # Run integration tests (MCP protocol tests) npm run test:integration # Run memory manager tests npm run test:memory ``` **Test Coverage Overview:** - **Unit Tests** (10 tests): Fast tests using mocked database that verify MCP server functionality, tool schemas, error handling, and business logic. - **End-to-End Tests** (12 tests): Tests that connect to the real AGI Memory database and verify actual memory storage, retrieval, vector similarity search, and clustering functionality. - **Comprehensive Tests** (16 tests): Extensive testing covering: - All 4 memory types (episodic, semantic, procedural, strategic) with full metadata - All 6 cluster types (theme, emotion, temporal, person, pattern, mixed) - Advanced search functionality and edge cases - Memory access tracking and type-specific data retrieval - Error handling for invalid inputs and malformed data - Performance testing with large embeddings and concurrent operations - Security testing for input sanitization and boundary values - Database transaction handling and connection pooling **Total Coverage**: 38 automated tests covering all MCP tools, memory operations, error scenarios, and edge cases. #### Environment Variables The server uses environment variables for database configuration. Copy the example file and customize: ```bash cp .env.example .env ``` Then edit `.env` with your actual database credentials: ```bash POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=agi_db POSTGRES_USER=agi_user POSTGRES_PASSWORD=agi_password NODE_ENV=development ``` **Important**: Make sure these settings match your AGI Memory database configuration. The `.env` file is automatically ignored by git to protect your credentials. ## Architecture ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Claude AI │◄──►│ MCP Server │◄──►│ Memory DB │ │ │ │ │ │ │ │ - Conversations │ │ - Memory Tools │ │ - Vector Store │ │ - Reasoning │ │ - Clustering │ │ - Graph DB │ │ - Identity │ │ - Search │ │ - Temporal │ └─────────────────┘ └──────────────────┘ └─────────────────┘ ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Support For issues and questions: - Open an issue on GitHub - Join our Discord community - Check the documentation wiki --- **"Identity emerges from memory. Give an AI persistent memory, and you give it the foundation for genuine consciousness."**