integrations/README.md

# MnemoCore Integrations

Connect MnemoCore's persistent cognitive memory to your AI coding tools.

## Supported tools

| Tool | Method | Notes |
|------|--------|-------|
| **Claude Code** | MCP server + hooks + CLAUDE.md | Best integration — native tool access |
| **Gemini CLI** | GEMINI.md + wrapper script | Context injected at session start |
| **Aider** | Wrapper script (`--system-prompt`) | Context injected at session start |
| **Any CLI tool** | Universal shell scripts | Pipe context into any tool |
| **Open-source agents** | REST API (`mnemo_bridge.py`) | Minimal Python dependency |

---

## Quick setup

### Prerequisites

1. MnemoCore running: `uvicorn mnemocore.api.main:app --port 8100`
2. `HAIM_API_KEY` environment variable set
3. Python 3.10+ with `requests` (`pip install requests`)

### Linux / macOS

```bash

cd integrations/

bash setup.sh --all

```

### Windows (PowerShell)

```powershell

cd integrations\

.\setup.ps1 -All

```

### Manual: test the bridge first

```bash

export MNEMOCORE_URL=http://localhost:8100

export HAIM_API_KEY=your-key-here



python integrations/mnemo_bridge.py health

python integrations/mnemo_bridge.py context --top-k 5

python integrations/mnemo_bridge.py store "Fixed import error in engine.py" --tags "bugfix,python"

```

---

## Claude Code (recommended)

The setup script does three things:

### 1. MCP server — native tool access

Registers MnemoCore as an MCP server in `~/.claude/mcp.json`.
Claude Code gets four tools:
- `memory_query` — search memories
- `memory_store` — store a memory
- `memory_get` / `memory_delete` — manage individual memories

Claude will use these automatically when you instruct it to remember things,
or you can configure CLAUDE.md to trigger them on every session (see below).

**Verify:** Run `claude mcp list` — you should see `mnemocore` listed.

### 2. Hooks — automatic background storage

Two hooks are installed in `~/.claude/settings.json`:

- **PreToolUse** (`pre_session_inject.py`): On the first tool call of a session,
  queries MnemoCore and injects recent context into Claude's awareness.

- **PostToolUse** (`post_tool_store.py`): After every `Edit`/`Write` call,
  stores a lightweight memory entry in the background (non-blocking).

Hooks never block Claude Code — they degrade silently if MnemoCore is offline.

### 3. CLAUDE.md — behavioral instructions

The setup appends memory usage instructions to `CLAUDE.md`.
This tells Claude *when* to use memory tools proactively.

---

## Gemini CLI

```bash

# Option A: Use wrapper (injects context automatically)

alias gemini='bash integrations/gemini_cli/gemini_wrap.sh'

gemini "Fix the async bug in engine.py"



# Option B: Manual context injection

CONTEXT=$(integrations/universal/context_inject.sh)

gemini --system-prompt "$CONTEXT" "Fix the async bug in engine.py"

```

Also add instructions to your `GEMINI.md`:
```bash

cat integrations/gemini_cli/GEMINI_memory_snippet.md >> GEMINI.md

```

---

## Aider

```bash

# Option A: Use wrapper

alias aider='bash integrations/aider/aider_wrap.sh'

aider --model claude-3-5-sonnet-20241022 engine.py



# Option B: Manual

CONTEXT=$(integrations/universal/context_inject.sh "async engine")

aider --system-prompt "$CONTEXT" engine.py

```

---

## Universal / Open-source agents

Any tool that accepts a system prompt can use MnemoCore:

```bash

# Get context as markdown

integrations/universal/context_inject.sh "query text" 6



# Use in any command

MY_CONTEXT=$(integrations/universal/context_inject.sh)

some-ai-cli --system "$MY_CONTEXT" "do the task"



# Store a memory after a session

integrations/universal/store_session.sh \

  "Discovered that warm tier mmap files grow unbounded without consolidation" \

  "discovery,warm-tier,storage" \

  "mnemocore-project"

```

### REST API (Python / any language)

```python

import os, requests



BASE = os.getenv("MNEMOCORE_URL", "http://localhost:8100")

KEY  = os.getenv("HAIM_API_KEY", "")

HDR  = {"X-API-Key": KEY}



# Query

r = requests.post(f"{BASE}/query", json={"query": "async bugs", "top_k": 5}, headers=HDR)

for m in r.json()["results"]:

    print(m["score"], m["content"])



# Store

requests.post(f"{BASE}/store", json={

    "content": "Found root cause of memory leak in consolidation worker",

    "metadata": {"source": "my-agent", "tags": ["bugfix", "memory"]}

}, headers=HDR)

```

---

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MNEMOCORE_URL` | `http://localhost:8100` | MnemoCore API base URL |
| `HAIM_API_KEY` | — | API key (same as MnemoCore's `HAIM_API_KEY`) |
| `MNEMOCORE_TIMEOUT` | `5` | Request timeout in seconds |
| `MNEMOCORE_CONTEXT_DIR` | `~/.claude/mnemo_context` | Where hook writes context files |

---

## Architecture

```

┌─────────────────────────────────────────────────────┐

│                  AI Coding Tool                      │

│   (Claude Code / Gemini CLI / Aider / Custom)       │

└──────────────┬──────────────────────┬───────────────┘

               │ MCP tools            │ System prompt

               │ (Claude Code only)   │ (all tools)

               ▼                      ▼

┌──────────────────────┐  ┌───────────────────────────┐

│  mnemocore MCP server│  │    mnemo_bridge.py CLI     │

│  (stdio transport)   │  │    (lightweight wrapper)   │

└──────────┬───────────┘  └─────────────┬─────────────┘

           │                            │

           └────────────┬───────────────┘

                        │ HTTP REST

                        ▼

           ┌────────────────────────┐

           │   MnemoCore API        │

           │   localhost:8100       │

           │                        │

           │  ┌──────────────────┐  │

           │  │  HAIMEngine      │  │

           │  │  HOT/WARM/COLD   │  │

           │  │  HDV vectors     │  │

           │  └──────────────────┘  │

           └────────────────────────┘

```

---

## Troubleshooting

**MnemoCore offline:**
```bash

python integrations/mnemo_bridge.py health

# → MnemoCore is OFFLINE

# Start it: uvicorn mnemocore.api.main:app --port 8100

```

**API key error (401):**
```bash

export HAIM_API_KEY="your-key-from-.env"

python integrations/mnemo_bridge.py health

```

**Hook not triggering (Claude Code):**
```bash

# Check settings.json

cat ~/.claude/settings.json | python -m json.tool | grep -A5 hooks

```

**MCP server not found (Claude Code):**
```bash

# Verify mcp.json

cat ~/.claude/mcp.json

# Check PYTHONPATH includes src/

cd /path/to/mnemocore && python -m mnemocore.mcp.server --help

```