Skip to content

cognitivecomputations/agi-mcp-server

BranchesTags

Repository files navigation

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:

  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:

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:

  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 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

  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."

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages