memory-bridge/README.md

memory-bridge

A lightweight local HTTP server that gives Claude (or any LLM) persistent long-term memory via a local vector database. No cloud. No API keys. Runs fully on your machine.

Pairs with Desktop Commander — Claude can call these endpoints from any conversation to store and recall context across sessions.

---

Quick start

Option A — Full install (recommended)

cd memory-bridge
chmod +x install.sh
./install.sh

This will:

1. Install npm dependencies
2. Pull the nomic-embed-text embedding model via Ollama (~274 MB, one-time)
3. Register a launchd agent so the server starts on every login
4. Print your auth token

Option B — Manual start

npm install
node server.js

Your auth token is printed to stdout on first run and persisted to ~/.memory-bridge/.env.

---

Configuration

All config lives in ~/.memory-bridge/.env (auto-generated on first run):

Variable	Default	Description
MEMORY_BRIDGE_TOKEN	auto-generated	Bearer token for API auth
MEMORY_BRIDGE_PORT	3722	Port to listen on
OLLAMA_URL	http://localhost:11434	Ollama base URL

---

API reference

All endpoints except GET /health require:

Authorization: Bearer <your-token>

GET /health

Returns server status. No auth required.

curl http://localhost:3722/health

{
  "status": "ok",
  "version": "1.0.0",
  "embeddingMode": "ollama",
  "memoriesCount": 42
}

---

POST /store

Embed and persist a memory.

curl -X POST http://localhost:3722/store \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "The database migration runs every Sunday at 2am UTC", "tags": ["ops", "db"], "source": "conversation"}'

{ "id": "550e8400-...", "createdAt": "2026-03-21T10:00:00.000Z" }

Field	Type	Required	Description
text	string	yes	The memory content to embed and store
tags	string[]	no	Optional labels for filtering
source	string	no	Where this memory came from

---

POST /recall

Semantic search over stored memories.

curl -X POST http://localhost:3722/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "database maintenance schedule", "limit": 5}'

{
  "memories": [
    {
      "id": "550e8400-...",
      "text": "The database migration runs every Sunday at 2am UTC",
      "tags": ["ops", "db"],
      "source": "conversation",
      "createdAt": "2026-03-21T10:00:00.000Z",
      "score": 0.94
    }
  ]
}

Field	Type	Default	Description
query	string	required	Natural language search query
limit	number	10	Max results returned (max 100)
tags	string[]	[]	Filter results to only these tags

---

POST /forget

Delete a memory by ID.

curl -X POST http://localhost:3722/forget \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "550e8400-..."}'

{ "message": "forgotten", "id": "550e8400-..." }

---

GET /list

List all memories, paginated.

curl "http://localhost:3722/list?page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [...],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "pages": 3
}

---

How Claude uses it

Configure Claude's system prompt to call these endpoints at the start and end of each conversation:

At the start of each conversation, call POST /recall with the current topic
to retrieve relevant memories. At the end of each conversation, call POST /store
to persist any important facts, decisions, or user preferences discovered.

With Desktop Commander, Claude can make HTTP requests directly. Add the server details to Claude's context:

memory-bridge: http://localhost:3722
Authorization: Bearer <your-token>

Example workflow

1. User asks: "What did we decide about the auth system last month?"
2. Claude calls POST /recall with { "query": "auth system decisions" } → retrieves relevant memory with high score
3. Claude answers informed by past context
4. At conversation end, Claude calls POST /store to record new decisions made this session

---

Embedding modes

Mode	Quality	Requires
ollama	Semantic — understands paraphrases and synonyms	Ollama + nomic-embed-text
tfidf	Keyword — exact term matching with bigrams	Nothing (zero-config fallback)

The server detects Ollama automatically at startup. Run GET /health to see the active mode.

---

Logs & persistence

Path	Contents
~/.memory-bridge/index/	Vector index (vectra)
~/.memory-bridge/.env	Auth token and config
~/.memory-bridge/server.log	Stdout (when running as launchd service)
~/.memory-bridge/server-error.log	Stderr (when running as launchd service)

---

Uninstall

launchctl unload ~/Library/LaunchAgents/com.memory-bridge.plist
rm ~/Library/LaunchAgents/com.memory-bridge.plist
rm -rf ~/.memory-bridge   # deletes all stored memories