Metadata-Version: 2.4
Name: hippmem-mcp
Version: 0.4.4
Summary: MCP server for HIPPMEM — give AI tools long-term associative memory
Project-URL: Homepage, https://github.com/hippmem/hippmem-mcp
Project-URL: Repository, https://github.com/hippmem/hippmem-mcp
Author-email: hippmem <hippmem@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: hippmem>=0.4.3
Requires-Dist: mcp>=2.0.0
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: mcp[cli]>=2.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# hippmem-mcp

**MCP server for [HIPPMEM](https://github.com/hippmem/hippmem) — give AI tools long-term associative memory.**

[![CI](https://github.com/hippmem/hippmem-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hippmem/hippmem-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/hippmem-mcp.svg)](https://pypi.org/project/hippmem-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/hippmem-mcp.svg)](https://pypi.org/project/hippmem-mcp/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

**Ecosystem**: [Rust engine](https://github.com/hippmem/hippmem) · [Python bindings](https://github.com/hippmem/hippmem-py) · [MCP server](https://github.com/hippmem/hippmem-mcp)

---

## What is HIPPMEM?

[HIPPMEM](https://github.com/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](https://modelcontextprotocol.io/) 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

```bash
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).

```bash
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](#running-as-a-service-macos))
  and point every client at the same URL

### Claude Desktop

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

```json
{
  "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.

| Variable | Default | Description |
|----------|---------|-------------|
| `HIPPMEM_STORE_PATH` | *(engine default: `./hippmem_data` relative to the server's working directory)* | Fixed memory store path. Set for a shared global memory across projects. Unset gives one store per working directory — per-project for Claude Code (which launches the server from the project dir), global for clients that don't. |
| `HIPPMEM_EMBEDDER_PROVIDER` | `hash` | Embedder: `hash` (offline, default) or `neural` (API-based, higher accuracy). Any other value fails fast at startup. |
| `HIPPMEM_EMBEDDING_BASE_URL` | *(none — required when `neural`)* | OpenAI-compatible API endpoint, e.g. `https://api.openai.com/v1` |
| `HIPPMEM_EMBEDDING_MODEL` | *(none — required when `neural`)* | Model name, e.g. `text-embedding-3-small` |
| `OPENAI_API_KEY` | *(none)* | API key — required when `HIPPMEM_EMBEDDER_PROVIDER=neural` |

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`):

```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](docs/best-practices.md) for the full retrieval/feedback loop.

### Other MCP Clients

hippmem-mcp speaks standard MCP over streamable HTTP. Configure any [MCP-compatible client](https://modelcontextprotocol.io/clients) 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
<?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

| Tool | Description |
|------|-------------|
| `write_memory` | Write a memory. The engine automatically discovers associations with existing memories. Supports `content_type` (Decision, Preference, ProjectKnowledge, TaskState, Correction, Event, Reflection) and `importance` (0.0–1.0). |
| `retrieve_memories` | Cross-session associative recall via multi-channel seed retrieval + spreading activation. Returns `{retrieval_id, results}` — each result is scored and explains *why* it was recalled via `dimensions`. Supports `top_k` (default 3) and `max_hops`. |
| `feedback_memory` | Send usage feedback for a previous retrieval (`retrieval_id` from `retrieve_memories`): `referenced`, `user_confirmed_correct`, `task_succeeded`, or `user_rejected`. Strengthens what was used, weakens what was rejected — this is the loop that makes retrieval more accurate over time. |

## Development

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for commit conventions, PR workflow, and DCO requirements.

## Documentation

- [Best Practices](docs/best-practices.md) — when to write, how to query, prompt templates
- [HIPPMEM main project](https://github.com/hippmem/hippmem) — engine architecture, concepts, and API reference
- [MCP specification](https://modelcontextprotocol.io/) — Model Context Protocol
- [Changelog](CHANGELOG.md)
- [Security policy](SECURITY.md)

## License

Apache 2.0. See [LICENSE](LICENSE) and [COPYRIGHT](COPYRIGHT).

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