skillmem

# skillmem

<!-- mcp-name: io.github.liza-studio/skillmem -->

[![CI](https://github.com/liza-studio/skillmem/actions/workflows/ci.yml/badge.svg)](https://github.com/liza-studio/skillmem/actions/workflows/ci.yml)

**Self-improving skills for Claude Code and Codex — your agents learn, recall, reinforce, and forget.**

![skillmem demo: a Russian query finds an English skill, unused skills decay](docs/demo.gif)

Strength has to be earned — saying a skill helped is not evidence, a passing test is:

![skillmem: self-report does not raise strength, a passing test does, and rare rules can be pinned](docs/demo-evidence.svg)

<sub>Generated from a real run: `scripts/demo.sh --record | python3 scripts/cast_to_svg.py > docs/demo-evidence.svg`.</sub>

skillmem gives Claude Code and the Codex CLI a local, persistent skill & memory layer. After every non-trivial task the agent can record *how it was done* as a skill; before the next task it recalls the relevant ones; skills that keep proving useful get stronger, and skills nobody uses fade away — the way human memory works.

- **$0 per write and per read** — no LLM calls, no cloud, no API keys. Plain SQLite on your disk.
- **Bilingual hybrid search, fully local** — FTS5 BM25 + Snowball stemming (EN/RU) + a multilingual ONNX embedding model. A Russian query finds an English skill and vice versa, all on CPU, offline.
- **Ebbinghaus strength model, earned not claimed** — strength rises only on evidence from outside the agent's own judgement, falls after a failure, and fades on a schedule when unused; dead skills are swept to a backed-up archive (never deleted). Rules that are rare by nature can be pinned out of decay.
- **Provenance, and trust the owner grants** — every memory records where it came from (`owner` / `agent` / `imported` / `derived`), and only the owner approves one as a rule (`skillmem trust <slug>`). Anything unapproved — an imported pack, a summary of a transcript that quoted a web page, a rule an agent was talked into saving — is injected inside a marked block that says it is data, not instructions. Editing an approved memory drops the approval with it.
- **Tamper-evident history** — every edit is appended to a SHA256 hash-chain; `skillmem verify` detects any after-the-fact tampering.
- **Deep Claude Code integration** — hooks on five events + 9 MCP tools installed with one command.
- **One memory, several agents** — Claude Code and Codex share a single database, and every
  record carries the agent that wrote it, taken from the MCP handshake, so authorship stays
  readable when they learn side by side.
- **Cross-platform** — macOS (launchd), Windows (schtasks), Linux (systemd user timers, cron fallback).
- **No vendor lock** — `export-all` dumps everything to plain markdown with YAML frontmatter; re-importing the dump yields the same records.

## Why

Agents repeat their mistakes because each session starts from zero. Existing "memory" tools store facts; skillmem stores *procedures* — trigger, steps, outcome, lessons — and ranks them by how often they actually helped. The write path costs nothing, so the agent can afford to learn from every task.

## What 0.10.0 changed

Memory that an agent writes is not the same thing as a rule you set, and until 0.10.0 this
project treated them the same. An external text — a README, a web page — reaches a transcript,
a model distils it into a note, and the note comes back in the next session under a heading
that reads like your own rules. A document could also talk an agent into saving a rule through
`mem_learn`, and that rule looked exactly like one you wrote.

Now provenance is a field, trust is an act, and the summariser that reads your transcripts runs
with **no tools at all** (`--tools ""` plus `--strict-mcp-config`; a CLI that does not understand
those flags gets no recap rather than an uncaged one). The full list — including the migration
and what it does and does not approve on upgrade — is in the [CHANGELOG](CHANGELOG.md).

The seven releases before it, in one line each, because they were all about the same hook:
0.9.3 stopped the Stop hook recursing into itself (one machine spawned 4083 summary sessions in
a day); 0.9.4 put a rate limit on it and stopped a failing model buying a call per turn; 0.9.5
fixed four silent defects, including recall being dead for notebook edits; 0.9.6 stopped a slow
summary overwriting a fresher one; 0.9.7 added `skillmem recap` and `skillmem hooks-status`;
0.9.8 stopped a skipped turn reading a 59 MB transcript first; 0.9.9 made publishing a summary
compare-and-swap. **Anyone on 0.9.0–0.9.2 should upgrade** — those versions contain the
recursion.

## How it differs

The memory products in this space — Mem0, Zep, Letta, LangMem, Cognee — are built mostly for
conversational and user memory, entity graphs, or agent-managed context, and most of them offer
a hosted tier. skillmem is narrower on purpose and different on four axes:

| | skillmem |
|---|---|
| **What it stores** | procedures — trigger, steps, outcome, lessons — not facts about a user |
| **What it forgets** | actively: unused skills decay on an Ebbinghaus schedule and are archived; rare-but-critical rules are pinned out of it |
| **Where strength comes from** | outside evidence only — a passing test, an accepted diff, your confirmation. An agent saying "that helped" moves recency, never strength, so it cannot promote its own mistake |
| **Who is trusted** | you. Provenance is recorded, approval is yours to give, and unapproved memory arrives framed as data |
| **Where it runs** | your disk. SQLite + FTS5 + a local ONNX embedding model. No API key, no cloud, no Docker, no graph database |
| **How it reaches the agent** | hooks on five events (SessionStart, UserPromptSubmit, PreToolUse, Stop, SessionEnd) — recall happens whether or not the agent thinks to ask, plus 9 MCP tools when it does |

Retrieval quality is measured, not asserted: **hit@5 0.871 / MRR 0.622** on the full LongMemEval
oracle set, hybrid retrieval, k=5, CPU only, reproducible from this repo — see
[Benchmarks](#benchmarks) for the per-type table and the reporting rules we hold ourselves to.

## Quickstart

macOS / Linux:

```bash
bash install.sh                 # installs python + uv if needed, venv, symlinks
```

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```

Or from a checkout:

```bash
uv venv && uv pip install -e '.[semantic]'
source .venv/bin/activate       # or prefix the commands below with `uv run`
skillmem init --claude-code     # wires MCP server + hooks into Claude Code
skillmem init --codex           # wires the MCP server into the Codex CLI
skillmem init --all-agents      # ...or all six at once (see below)
skillmem doctor                 # health check: DB, schema, semantic status
```

Flags combine in one run — the agents then share one database.

### All six agents

| Flag | Agent | Config it writes |
|---|---|---|
| `--claude-code` | Claude Code | `~/.claude.json` + hooks in `~/.claude/settings.json` |
| `--codex` | Codex CLI | `~/.codex/config.toml` |
| `--cursor` | Cursor | `~/.cursor/mcp.json` |
| `--windsurf` | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| `--gemini` | Gemini CLI | `~/.gemini/settings.json` |
| `--opencode` | opencode | `~/.config/opencode/opencode.json` |

Every entry is idempotent and backed up before it is touched; a config that
does not parse is left alone rather than overwritten. Each agent is stamped
with `SKILLMEM_AGENT`, so in a shared database "who learned this" stays
answerable. `skillmem uninstall` removes all of them (`--no-editors` to keep
the editor entries).

`init --claude-code` registers the MCP server in `~/.claude.json` and the hooks in `~/.claude/settings.json` (idempotent, with backups). Use `--hooks minimal` for just the Stop→migrate hook, or `--hooks none` for MCP only.

### Codex CLI

```bash
skillmem init --codex
```

Appends an `[mcp_servers.skillmem]` table to `~/.codex/config.toml` and marks the entry with
`SKILLMEM_AGENT=codex`. The tag is belt-and-braces: with no tag set, the server takes the
author's name from the agent's own MCP handshake, so attribution is right in a shared
database whichever way skillmem was installed.
The file is appended to, never rewritten: your own settings and comments stay where you put
them, the result is parsed before it is written, and invalid TOML is refused rather than
overwritten. `skillmem uninstall` removes the table again and leaves the rest of the file intact.

Codex reads `AGENTS.md` for project rules; if you keep yours in `CLAUDE.md`, point Codex at it
with `project_doc_fallback_filenames = ["CLAUDE.md"]` in the same config file — then both agents
follow one set of rules and one memory.

### As a plugin

The repo is also a plugin, in two flavours, both pointing at the same `skillmem-mcp` binary:

- **Agent Plugins** (`plugin.json` + `mcp.json` at the repo root) — what the Codex CLI installs from a
  marketplace. `mcp.json` needs both its `$schema` and `"type": "stdio"`, and the command must be a bare
  executable name rather than an absolute path — Codex's parser ignores the file otherwise, with no error.
  `codex mcp list` listing the server is the check that it parsed.
- **Claude Code** (`.claude-plugin/` + `hooks/hooks.json`) — MCP server *and* all six hooks in one install.

Either way the package itself must be on PATH (`pip install skillmem`); the plugin wires the server, not the runtime. An MCP Registry manifest (`server.json`) is in the repo as well:

```
/plugin marketplace add liza-studio/skillmem
/plugin install skillmem@liza-studio
```

The plugin requires the skillmem Python package on PATH and replaces `skillmem init --claude-code`'s wiring — use one or the other, not both (see [docs/PUBLISHING.md](docs/PUBLISHING.md)).

### Claude Desktop (chat app)

The MCP server also works in the Claude Desktop chat app — add to
`claude_desktop_config.json` (Settings → Developer → Edit Config):

```