# Harness Memory

> Project memory for your AI coding agents, in one local binary.

Harness Memory is a local stdio MCP server that gives Claude Code, Codex, OMP, PI, OpenCode and any other MCP client one shared project memory.

## What does Harness Memory do?

- **Search first, save last.** Agents search notes at the start of a task and save what they learn (fixes, decisions, where things live) before they finish.
- **Typed notes.** Notes have a kind: outcome, problem, fix, optimisation, location, decision or note, plus tags and the entities they are about.
- **A small entity graph.** entity_link relates two entities, for example ConfigLoader located_in src/config.rs, and entity_neighbors shows the relations around one.
- **Saved scripts.** Agents save a deterministic script by name so a repeated action runs without being worked out again. A teammate’s script runs only after you approve it.
- **Local SQLite with full-text search.** Notes live in a local SQLite database with FTS5 search, keyed per git repository. Search is stemmed English keyword search.
- **Optional vector search.** Adds notes close in meaning through one local embedder per computer. It is off until you enable it.
- **Secrets redacted on write.** Titles, bodies, tags, entity names and relation labels pass a secret filter before they are stored. It is a heuristic and does not catch everything.
- **Team memory.** Point every teammate’s server at one shared database so a fix one person’s agent saves is found by the next teammate’s agent.

## Which harnesses and tools does Harness Memory support?

| Harness | Support |
| --- | --- |
| Claude Code | Register with claude mcp add --scope user harness-memory -- harness-memory mcp. |
| Codex | Register with codex mcp add harness-memory -- harness-memory mcp, or in config.toml. |
| OMP (oh-my-pi) | Add an mcpServers entry in ~/.omp/agent/mcp.json, or use /mcp add. |
| PI | Recent versions read ~/.pi/agent/mcp.json. Older ones need the pi-mcp-adapter first. |
| OpenCode | Add a local entry to the mcp object of opencode.json. |
| Any other MCP client | Any MCP client can start the stdio server with harness-memory mcp. |

## Which platforms does Harness Memory run on?

- macOS (Apple Silicon and Intel)
- Linux (x86_64)
- Windows

## How do I install Harness Memory?

### macOS and Linux

```sh
curl -fsSL https://raw.githubusercontent.com/MSpiechowicz/harness-useful-memory/main/install.sh | sh
```

### Windows (PowerShell)

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/MSpiechowicz/harness-useful-memory/main/install.ps1 | iex"
```

## Is Harness Memory private? Where does my data live?

- Local by default. Without a team database the server opens no network connection, except that the embedder downloads its search model once when you turn vector search on.
- Notes live in one SQLite file, memory.sqlite3, in the harness-memory folder of your user data directory. The file is not encrypted.
- Secrets are redacted before anything is stored. The filter is a heuristic, so do not rely on it.
- Notes are untrusted data written by agents. Results say where each note came from, and agents are told to check notes against the code.
- Scripts run as you. A machine runs only scripts saved on it or approved by you there.

## Frequently asked questions

### What is Harness Memory?

Harness Memory is a stdio MCP server, shipped as one local binary called harness-memory. Agents such as Claude Code, Codex, OMP, PI and OpenCode search it at the start of a task and save what they learn, so the next session in the same repository starts better informed.

### Which coding agents work with Harness Memory?

Any MCP client can start it. The README documents setup for Claude Code, Codex, OMP, PI and OpenCode. Each harness keeps its MCP servers in its own settings, so you add the harness-memory entry once per harness. Harness Desktop can register it for you.

### How do I install Harness Memory?

On macOS and Linux run the curl install script from the README. On Windows run the PowerShell command. Both download the binary and checksums from the GitHub release and install nothing unless the SHA-256 matches. Then register it with each harness and check harness-memory --version.

### Where does Harness Memory store my notes?

In one SQLite file named memory.sqlite3, in the harness-memory folder of your user data directory. On Linux that is ~/.local/share/harness-memory, on macOS ~/Library/Application Support/harness-memory and on Windows %LOCALAPPDATA%\harness-memory. Set HARNESS_MEMORY_DIR to use another folder.

### Does Harness Memory send my notes anywhere?

Not by default. Without a team database the server opens no network connection. The embedder downloads its search model once if you turn vector search on. What an agent reads from memory goes to its model provider like the rest of its context.

### Is Harness Memory free and can a team share it?

It is open source under GPL-3.0-or-later. By default each person keeps a local SQLite file. Team memory points every teammate’s server at one shared database, which you set up and configure yourself.

### How does Harness Memory connect to Desktop and Skills?

Harness Desktop registers the server in every detected harness while Project memory is on in its Settings, and adds hooks that make agents search first and save last. The us-use-harness-memory skill in Harness Skills works with its MCP tools.

## Links

- Page: https://harness-useful.com/memory
- GitHub: https://github.com/MSpiechowicz/harness-useful-memory
- Releases: https://github.com/MSpiechowicz/harness-useful-memory/releases
- License: GPL-3.0-or-later
- Harness Useful home: https://harness-useful.com/
- FAQ: https://harness-useful.com/faq