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 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 database to be running first.
1. Set Up the Memory Database
# 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
# 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:
{
"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:
{
"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:
# 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:
{
"mcpServers": {
"agi-memory": {
"command": "/full/path/to/npx",
"args": ["-y", "github:cognitivecomputations/agi-mcp-server"],
"env": { /* ... your env vars ... */ }
}
}
}
After fixing the paths:
- Restart Claude Desktop completely (quit and reopen)
- Wait a few seconds for the MCP server to initialize
- Check that the AGI Memory database is running:
docker compose psin your agi-memory directory
Testing the server manually:
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:
cat ~/Library/Logs/Claude/mcp-server-agi-memory.log
Memory Tools
Orientation Tools
get_memory_health- Overall memory system statisticsget_active_themes- Recently activated memory patternsget_identity_core- Core identity and reasoning patternsget_worldview- Current belief systems and frameworks
Search & Retrieval
search_memories_similarity- Vector-based semantic searchsearch_memories_text- Full-text search across memory contentget_memory_clusters- View thematic memory groupingsactivate_cluster- Retrieve memories from specific themesget_memory- Access specific memory by ID
Memory Creation
create_memory- Store new episodic, semantic, procedural, or strategic memoriescreate_memory_cluster- Organize memories into thematic groups
Memory Types
Episodic Memories
Store specific experiences and events:
{
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:
{
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:
{
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:
{
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:
- Always start sessions with
get_active_themesandget_memory_health - Search for context when humans reference past interactions
- Activate relevant clusters for complex topic discussions
- Create memories for significant insights and breakthroughs
- 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 for complete schema documentation.
Development
Running Tests
The project includes comprehensive test suites with extensive coverage:
# 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:
cp .env.example .env
Then edit .env with your actual database credentials:
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
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- 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."