Metadata-Version: 2.2
Name: memory-bridge-mcp
Version: 1.2.0
Summary: Unified MCP memory server bridging Mind (concept graph) and Honcho (semantic vector) memory with episodic timeline and LLM synthesis
Author: LE-VAI
License: MIT License
Project-URL: Homepage, https://github.com/LE-VAI/memory-bridge
Project-URL: Repository, https://github.com/LE-VAI/memory-bridge
Project-URL: Documentation, https://github.com/LE-VAI/memory-bridge#readme
Keywords: mcp,memory,mind,honcho,llm,synthesis,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md

# Memory Bridge MCP

**Unified MCP memory server** — bridges Mind (concept graph) and Honcho (semantic vector) memory with episodic timeline and LLM synthesis into a single MCP query surface.

```
pip install memory-bridge-mcp
```

## What it does

Memory Bridge exposes 8 MCP tools that let any MCP-compatible agent (Claude Code, Codex, etc.) store and recall memories across three memory systems:

| Tool | Purpose |
|---|---|
| `bridge_remember` | Store a memory — auto-routes short facts to Mind, long content to Honcho |
| `bridge_recall` | Unified recall across both systems with Reciprocal Rank Fusion |
| `bridge_status` | Combined health report for all memory systems |
| `bridge_episode_record` | Record a structured session episode |
| `bridge_episode_recall` | Search episodic timeline by text, time, and tags |
| `bridge_timeline` | Chronological view of all session episodes |
| `bridge_synthesize` | Cortex Accelerator — synthesize knowledge across all memory |
| `bridge_contradictions` | Detect contradictory memories |

## Quick start

```bash
# Install
pip install memory-bridge-mcp

# Run as MCP server (stdio)
memory-bridge
```

The server speaks the [MCP protocol](https://modelcontextprotocol.io) over stdio. Configure it as an MCP server in your agent's config:

```json
{
  "mcpServers": {
    "memory-bridge": {
      "command": "memory-bridge"
    }
  }
}
```

## Memory systems

### Mind (concept graph)
A local, zero-dependency concept graph with spreading-activation recall, Ebbinghaus forgetting, and dream consolidation. Stored in `.mind/graph.json` in the working directory. The vendored `mind.py` module handles all graph operations.

### Honcho (semantic vector)
An optional semantic vector store running on `http://127.0.0.1:8000`. Provides embedding-based similarity search. If Honcho is unavailable, the bridge falls back to Mind only.

### Episodic (session timeline)
A JSONL-based append-only log of structured session episodes. Stored in `.memory-bridge/episodes.jsonl`. Supports text search, time-range filtering, tag filtering, and session filtering.

### Synthesis (Cortex Accelerator)
Optionally uses a local Ollama instance (`http://127.0.0.1:11434`) to synthesize related memories into concise summaries. Falls back to extractive key-sentence selection when LLM is unavailable.

## Configuration

The server reads these environment variables:

| Variable | Default | Description |
|---|---|---|
| `HONCHO_BASE_URL` | `http://127.0.0.1:8000/v3` | Honcho API endpoint |
| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama API endpoint |
| `OLLAMA_SYNTHESIS_MODEL` | `qwen3:8b` | Model for LLM synthesis |

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Agent      │     │   Agent      │     │   Agent      │
│ (Claude,     │     │ (Codex,      │     │ (any MCP)    │
│  Codex, ...) │     │  ...)        │     │              │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │ MCP stdio
                    ┌───────▼────────┐
                    │  Memory Bridge  │
                    │  MCP Server     │
                    └───┬────┬────┬──┘
                        │    │    │
              ┌─────────┘    │    └──────────┐
              ▼              ▼                ▼
       ┌──────────┐  ┌──────────┐  ┌──────────────┐
       │   Mind   │  │  Honcho  │  │  Episodic     │
       │  Graph   │  │  Vector  │  │  Timeline     │
       │ (local)  │  │ (HTTP)   │  │  (JSONL)      │
       └──────────┘  └──────────┘  └──────────────┘
```

## Zero dependencies

The core server uses only the Python standard library. No pip dependencies required. The vendored `mind.py` module is also zero-dependency.

## License

MIT
