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:

*Configuration content*

Alternative: Use directly from GitHub without local installation:

*Configuration content*

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:

*Configuration content*

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 ps in 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 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:

{
  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_themes and get_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."

Agi MCP Server

AGI MCP Server

Overview

Quick Start

Prerequisites

Installation

1. Set Up the Memory Database

2. Install and Run MCP Server

3. Connect to Claude Desktop

Memory Tools

Orientation Tools

Search & Retrieval

Memory Creation

Memory Types

Episodic Memories

Semantic Memories

Procedural Memories

Strategic Memories

Awakening Protocol

Database Schema

Development

Running Tests

Environment Variables

Architecture

Contributing

License

Support