hippmem-mcp

MCP server for HIPPMEM — give AI tools long-term associative memory.

Ecosystem: Rust engine · Python bindings · MCP server

What is HIPPMEM?

HIPPMEM is a native associative memory engine for AI agents, written in Rust. Instead of storing text chunks and searching them by vector similarity, it discovers associations between memories at write time and retrieves them via spreading activation at read time — so the AI recalls not just what was said, but how things connect and why.

It runs fully offline with a deterministic fallback backend.

What is hippmem-mcp?

hippmem-mcp wraps HIPPMEM as a Model Context Protocol server. Configure it once in Claude Desktop (or any MCP-compatible tool), and your AI assistant gains persistent, associative memory across sessions — no API key required.

Claude Code / Claude Desktop / other tools
        │  MCP (streamable HTTP)
        ▼
  hippmem-mcp  (one long-lived process owns the store)
        │  Python bindings
        ▼
  hippmem Engine (Rust)
        │
        ▼
  Local storage (redb + Tantivy + HNSW)

Key Features

• Zero config — pip install then one JSON block in your MCP client configuration; deterministic fallback backend works offline

• Write-time association discovery — entities, topics, goals, causal links extracted and scored automatically

• Spreading activation retrieval — multi-channel seed recall (BM25 + entity + semantic + temporal + topic) fused by RRF

• Graph evolution — co-activated connections strengthen (Hebbian learning); stale edges decay

• Explanation traces — every result shows why it was recalled via dimensions and matched_dimensions

• Single-file storage — one redb file + Tantivy full-text index + HNSW vector index; no external database

Install

pip install hippmem-mcp

Requires Python ≥ 3.11.

Configure

Quick start (server mode)

hippmem-mcp runs as a long-lived HTTP server that owns the memory store — multiple AI sessions connect to it and share one memory (a stdio process per session cannot share the store: the engine holds a single-writer lock).

hippmem-mcp                     # HTTP server on http://127.0.0.1:8080/mcp
hippmem-mcp --port 9000         # custom port (or $HIPPMEM_MCP_PORT)
hippmem-mcp --stdio             # debug/single-session path (MCP over stdout)

• Server logs go to ~/.hippmem/mcp.log

• The memory graph consolidates in the background (every 5 minutes after a write; $HIPPMEM_CONSOLIDATE_INTERVAL_SECONDS to tune)

• Start it once per machine (see Running as a service) and point every client at the same URL

Claude Desktop

Add to claude_desktop_config.json (or use "type": "http" where supported):

{
  "mcpServers": {
    "hippmem": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Environment Variables

The server reads these variables from the environment that launches it — the env block in your MCP client config (e.g. Claude Desktop) or your shell, not from a .env file (none is auto-loaded). .env.example is a reference template for that environment.

With HIPPMEM_EMBEDDER_PROVIDER=neural, all three API variables above are required — startup fails naming the missing ones. The deterministic fallback backend requires no API key, no GPU, and no network connection.

Claude Code

Claude Code supports MCP natively. Add to your Claude Code MCP config (.claude/mcp.json or project .mcp.json):

{
  "mcpServers": {
    "hippmem": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Then in any Claude Code session, retrieval is query-driven — trigger it when a task signal appears (a past decision, a user preference, an unknown constraint), not by bulk-loading at session start:

Before answering, use retrieve_memories to check whether we have relevant
memory about this topic. Query with the specific question, not the whole task.

See Best Practices for the full retrieval/feedback loop.

Other MCP Clients

hippmem-mcp speaks standard MCP over streamable HTTP. Configure any MCP-compatible client with the URL transport (http://127.0.0.1:8080/mcp) the same way. The --stdio path remains available for debugging or single-session use.

Running as a service (macOS)

A long-lived server is meant to stay up. With launchd (auto-start + crash restart), save the following to ~/Library/LaunchAgents/io.hippmem.mcp.plist and run launchctl load ~/Library/LaunchAgents/io.hippmem.mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>io.hippmem.mcp</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/hippmem-mcp</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/tmp/hippmem-mcp.err.log</string>
</dict>
</plist>

Tools

Development

git clone https://github.com/hippmem/hippmem-mcp.git
cd hippmem-mcp
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for commit conventions, PR workflow, and DCO requirements.

Documentation

• Best Practices — when to write, how to query, prompt templates

• HIPPMEM main project — engine architecture, concepts, and API reference

• MCP specification — Model Context Protocol

• Changelog

• Security policy

License

Apache 2.0. See LICENSE and COPYRIGHT.

The underlying HIPPMEM engine (hippmem) is AGPL-3.0-only. A commercial license is available — contact hippmem@gmail.com.

Licensing FAQ

Is the engine AGPL in practice even if I use this Apache-2.0 server? Yes. This package is a thin Python binding over the AGPL engine — any deployment that runs it is effectively distributing/using AGPL-covered code. The Apache-2.0 license covers the binding's own code; the engine underneath stays AGPL-3.0-only.

Does my own internal use trigger AGPL obligations? No. Personal/internal use — your own workflow, your own agents, data that never leaves your machine — is unaffected by AGPL's network clause. No obligations until you provide the software as a service to others or redistribute it.

When does the network clause trigger? Offering HIPPMEM as a service to users (a SaaS product, a hosted memory backend for your customers) triggers AGPL §13: you must offer the complete corresponding source of the AGPL-covered engine to those users. Redistributing the engine (bundling it into a distributed product) similarly triggers source-availability.

What if I want to use HIPPMEM in a commercial product without AGPL obligations? Contact hippmem@gmail.com for a commercial license. The project follows the proven dual-licensing model (MongoDB/Redis lineage): AGPL for open/community use, a paid license for commercial distribution.

Does using this package as an MCP server for my own AI assistant count as a service? No — that is personal/internal use. The trigger is providing a service to users, not using the software yourself.