hippocampus-mcp

Hippocampus MCP

Personal Knowledge MCP Server - Provides AI assistants with access to personal knowledge, preferences, and contextual information stored in AWS DynamoDB.

Features

• Personal Knowledge Management: Store and retrieve notes, preferences, and contextual information
• Semantic Search: Find relevant information using natural language queries
• Category Organization: Organize knowledge by categories (work, personal, technical, etc.)
• AWS Integration: Leverages DynamoDB for scalable, serverless storage
• MCP Protocol: Standard Model Context Protocol implementation for AI assistant integration

Prerequisites

• Node.js 18.0.0 or higher
• AWS Account with DynamoDB access
• AWS CLI configured with credentials (or AWS SSO profile)

Installation

Quick Start (Recommended)

Add to your MCP client configuration (e.g., ~/.kiro/settings/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "hippocampus-mcp": {
      "command": "npx",
      "args": ["-y", "hippocampus-mcp@latest"],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "us-east-1",
        "DYNAMODB_TABLE_NAME": "your-table-name"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

That's it! The MCP client will automatically download and run the server when needed.

Manual Installation

npm install -g hippocampus-mcp

Configuration

The server requires the following environment variables:

Variable	Description	Default	Required
AWS_PROFILE	AWS CLI profile name	-	No*
AWS_REGION	AWS region for DynamoDB	us-east-1	No
DYNAMODB_TABLE_NAME	DynamoDB table name	personal-knowledge	No

*Either AWS_PROFILE or standard AWS credentials (access key/secret) must be configured.

AWS Setup

1. Create DynamoDB Table

You can deploy the required infrastructure using AWS CDK (included in this package):

# Clone the repository
git clone https://github.com/yourusername/hippocampus-mcp.git
cd hippocampus-mcp

# Install dependencies
npm install

# Deploy infrastructure
npm run cdk:deploy

Or create manually:

• Table name: personal-knowledge (or your custom name)
• Partition key: PK (String)
• Sort key: SK (String)
• GSI: GSI1 with GSI1PK (String) and GSI1SK (String)

2. Configure AWS Credentials

# Option 1: AWS SSO
aws sso login --profile your-profile-name

# Option 2: AWS CLI credentials
aws configure

Usage with MCP Clients

Kiro IDE

Edit ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "hippocampus-mcp": {
      "command": "npx",
      "args": ["-y", "hippocampus-mcp@latest"],
      "env": {
        "AWS_PROFILE": "hc1",
        "AWS_REGION": "us-east-1",
        "DYNAMODB_TABLE_NAME": "hc1-model-knowledge-241763622848"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "hippocampus-mcp": {
      "command": "npx",
      "args": ["-y", "hippocampus-mcp@latest"],
      "env": {
        "AWS_PROFILE": "hc1",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "hippocampus-mcp": {
      "command": "npx",
      "args": ["-y", "hippocampus-mcp@latest"],
      "env": {
        "AWS_PROFILE": "hc1",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Available Tools

The server provides the following MCP tools:

Knowledge Management

• create_note - Create a new note with content and metadata
• get_note - Retrieve a specific note by ID
• update_note - Update an existing note
• delete_note - Delete a note
• list_notes - List all notes with optional filtering

Search

• search_notes - Semantic search across all notes
• search_by_category - Find notes by category

Preferences

• set_preference - Store a user preference
• get_preference - Retrieve a preference value
• list_preferences - List all preferences

Available Resources

The server exposes the following MCP resources:

• knowledge://notes - Access to all notes
• knowledge://preferences - Access to user preferences
• knowledge://categories - List of available categories

Example Interactions

User: "Remember that I prefer dark mode for all applications"
AI: [Uses set_preference tool]

User: "What are my preferences for UI themes?"
AI: [Uses get_preference tool]

User: "Create a note about the AWS CDK deployment process"
AI: [Uses create_note tool]

User: "Find all my notes about AWS"
AI: [Uses search_notes tool]

Development

Local Development

# Clone repository
git clone https://github.com/yourusername/hippocampus-mcp.git
cd hippocampus-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Run tests
npm test

Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector npx hippocampus-mcp

Security Considerations

• AWS credentials are never transmitted - they remain local to your machine
• All data is stored in your own AWS account
• The server runs locally and communicates via stdio (no network exposure)
• Follow AWS IAM best practices for credential management

Cost Considerations

• DynamoDB: Pay-per-request pricing (very low cost for personal use)
• Typical usage: < $1/month for individual users
• No additional AWS services required

Troubleshooting

Server won't start

• Verify AWS credentials: aws sts get-caller-identity --profile your-profile
• Check DynamoDB table exists: aws dynamodb describe-table --table-name your-table --profile your-profile
• Review logs in MCP client (usually stderr output)

Permission errors

• Ensure IAM user/role has DynamoDB permissions:
  • dynamodb:PutItem
  • dynamodb:GetItem
  • dynamodb:Query
  • dynamodb:Scan
  • dynamodb:UpdateItem
  • dynamodb:DeleteItem

Connection issues

• Verify network connectivity to AWS
• Check AWS region configuration
• Ensure MCP client is properly configured

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE file for details.

Support

• Issues: https://github.com/yourusername/hippocampus-mcp/issues
• Documentation: https://github.com/yourusername/hippocampus-mcp/wiki

Related Projects

• Model Context Protocol
• AWS MCP Servers
• MCP TypeScript SDK