Hippocampal Memory

An MCP server for neuroanatomically-inspired memory consolidation using Neo4j and semantic search.

Features

• Episodic Memory Encoding: Create memory events with emotional valence and temporal context
• Semantic Retrieval: Vector similarity search using OpenAI embeddings
• Graph Operations: Full Cypher query support for reading and writing
• Relationship Tracking: Monitor bond strength evolution over time
• Extensible Schema: Additional tools in hippocampus-extension.mjs ready for integration

Quick Start

See CHECKLIST.md for daily startup instructions.

1. Install Dependencies

npm install

2. Setup Neo4j

You need Neo4j Desktop running locally with a database on port 7687.

3. Initialize Schema

npm run setup-schema

4. Setup Tunnel (for remote access)

Start ngrok to expose your local Neo4j:

ngrok tcp 7687

Copy the tunnel URL (e.g., tcp://2.tcp.us-cal-1.ngrok.io:12841)

5. Configure Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "hippocampal-memory": {
      "command": "node",
      "args": ["C:\\Users\\harve\\Neo4j\\hippocampal-mcp-server.mjs"],
      "env": {
        "NEO4J_URI": "bolt://YOUR_NGROK_URL",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "OPENAI_API_KEY": "your_openai_key"
      }
    }
  }
}

6. Start Claude Desktop

The MCP server will connect automatically.

Available Tools (8)

Hippocampus Module (Biomimetic Schema)

1. hippocampus_write_event - Structured event creation with Who/Why/What/Where/Effects blocks
2. hippocampus_write_reflection - Agent-relative memory slices with egocentric perspective
3. hippocampus_search_events - Pattern completion retrieval with temporal/participant/effect filters

Core Memory Tools

4. encode_memory - Save episodic memories with vector embeddings
5. recall_memory - Semantic + temporal + emotional search
6. query_graph - Read-only Cypher queries
7. mutate_graph - Write operations (CREATE, MERGE, etc.)
8. evolve_bond - Track relationship dynamics over time

Architecture

Current Setup:

• Neo4j Desktop running locally on port 7687
• ngrok tunnel for remote access
• Claude Desktop connects via stdio transport
• Render deployment at https://hippocampal-memory-mcp.onrender.com (HTTP/SSE transport)

Files:

• hippocampal-mcp-server.mjs - Main server (stdio for Claude Desktop)
• remote-mcp-server.mjs - HTTP/SSE server (for remote connections)
• hippocampus-extension.mjs - Additional biomimetic tools
• setup-vector-index.mjs - Schema initialization
• test-connection.mjs - Local connection test
• test-tunnel.mjs - Tunnel connection test

Schema

Core Nodes:

• Event - Episodic memories with vector embeddings
• Person - Human and AI entities
• Project - Ongoing work
• Concept - Abstract ideas
• Place, Catalyst, Entity, Target, Effect, Reflection, Agent (extension schema)

Key Relationships:

• INVOLVES - Event → Entity (with role & salience)
• PRECEDED - Event → Event (causal chains)
• CONSOLIDATED_TO - Event → Concept/Person/Project
• BOND - Person ↔ Person (with strength trajectory)
• PARTICIPATED_IN, CATALYZED_BY, HELD_AT, HAD_EFFECT_ON, etc. (extension schema)

Indexes:

• Vector index on Event.embedding (1536 dimensions, cosine similarity)
• Unique constraints on id fields for Person, Project, Concept, Event

Important Notes

• ngrok URL changes on every restart (unless you pay for static URL)
• Update NEO4J_URI in Claude Desktop config when ngrok URL changes
• Neo4j Desktop must be running before starting Claude Desktop
• Environment variables are in Claude Desktop config (NOT .env file)
• Render deployment requires persistent Neo4j (Aura) - local tunnel won't work

Testing

Test local connection:

node test-connection.mjs

Test tunnel connection:

node test-tunnel.mjs

Documentation

• CHECKLIST.md - Daily startup and tool addition guide
• neo4j-agent.instructions.md - Comprehensive Neo4j/Cypher/GraphQL guide
• docs/ - Archived setup guides and deployment notes

Deployment

Currently deployed to Render at: https://hippocampal-memory-mcp.onrender.com

For deployment details, see archived docs.