skillmem

skillmem

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

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

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

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) matches inflected forms within a language; the multilingual ONNX embedder is what lets a Russian query find an English skill, so install the semantic extra if you work across both. 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 ). 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. An agent cannot change a memory the owner wrote or approved: it writes a proposal under a new slug.
• 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 six 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. One destination per database: the exporter prunes its own stale files via a manifest, and refuses a directory another database exports to rather than overwrite its backup.

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.

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:

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 for the per-type table and the reporting rules we hold ourselves to.

Does a new session actually remember the last one? Measured on a real database, agent-level (see Benchmarks):

Quickstart

macOS / Linux:

pip install 'skillmem[semantic]'   # or: uv tool install 'skillmem[semantic]'

skillmem doctor # downloads the embedding model once (~220 MB)

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File install.ps1

Or from a checkout:

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

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 no hooks at all (only the deny rules for the owner-only commands, below), or --hooks none for MCP only. Hand-written memory files are imported with skillmem migrate --source ; there is no per-turn import hook.

Codex CLI

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* every hook 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).

A plugin cannot add permission rules, so the plugin path has no deny rules for the owner-only commands (trust, rm, skills-archive, skills-restore, skills rm, import-vault, uninstall --purge-db) — only their TTY check, which a pseudo-terminal gets past. skillmem init --claude-code installs both. Neither is a wall against an agent that has a shell: the rules match the command as written, and a quote inside the verb (skillmem tr''ust x under script) matches none of them. If agents run unattended with Bash on this machine, do not rely on them. The rules are a substring mat