io.github.arnaugonzalezPublished by GitHub account arnaugonzalezv0.2.1Updated Nov 11, 2026
Markdown memory for coding agents that audits itself: drift reports and session digests.
The publisher's own server: Memory.fit
Local markdown memory wiki for coding agents, with search, session checkpoints and drift reports on what the memory got wrong.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
Memory for coding agents that reviews itself.
[CI] [License: MIT] [Python 3.11+]
Try it · What it answers · Connect your agent · How it works · vs. alternatives
Your agents write everything down. Nobody reads it back.
Every memory tool for coding agents helps them remember more. None of them mention that half of what they remember expired in July. memory-boost keeps a plain-markdown memory your agents read and write over MCP, and then does the unglamorous part: it audits that memory and your own sessions, and tells you what drifted. Politely, with numbers.
Think of it as a code review for what your agents remember and a fitness tracker for how you work
with them. Mostly the fitness tracker: mine told me my most-failed command was cd. Sixty-nine
times.
Using an AI agent? Point Claude Code, Codex, Cursor or Gemini CLI at this repo: AGENTS.md tells it how to install memory-boost, seed a wiki and run the reports for you.
No install needed; the wiki lands in ~/.local/share/memory-boost:
To keep it in Claude Code, install the plugin. It brings the MCP server, the session-start brief and the skills in one step; it only needs uv on your PATH.
Other agents, or the CLI on its own: uv tool install memory-boost==0.2.1 (or
pipx install memory-boost==0.2.1). Or let your agent do it: see Install from your agent.
Paste this into Claude Code, Codex, Cline or Cursor:
Install memory-boost 0.2.1 by following https://github.com/arnaugonzalez/memory-boost/blob/main/llms-install.md : install the CLI with
uv tool install memory-boost==0.2.1, runmemory-boost init, registermemory-boost serveas a stdio MCP server namedmemory, check that it answers with ninememory_*tools, then runmemory-boost driftand show me the output. Ask me before writing outside the memory home (~/.local/share/memory-boost) or editing any global agent config.
The agent-oriented steps (stdio and serve --http, per harness, with checks) are in
llms-install.md.
You come back to acme-api and the agent still trusts everything it wrote down. drift says
which of it no longer holds: a Postgres pin whose review date passed in June, a superseded decision
that points nowhere, projects that went silent. page shows why the pin was made, so you can
decide in a minute. lessons brings over what pixel-notes learned about retrying jobs, because
both projects run background jobs. Bundled example data (memory-boost init --example), recorded
with vhs from docs/demo.tape.
Five weeks of the author's own daily use: 29 decisions, 24 projects, 657 Claude Code transcripts. Output as produced; only project and file names are replaced.
Every line is a habit to change, a decision to revisit, or a rule worth writing down. None of it needed a new tool: the data was already on disk. It needed a reader.
projects/*.md, decisions/*.md, concepts/*.md, log.md. Plain
markdown; edit by hand, keep it in git. SQLite FTS5 index as a disposable cache. Nine MCP
tools for any harness: memory_brief, memory_recall, memory_page, memory_save,
memory_checkpoint, memory_resume, memory_drift, memory_lesson, memory_shelf.
memory_shelf (CLI: memory-boost shelf "idea") appends a dated one-line idea to
concepts/idea-shelf.md without the agent reading the page back.status: and review_by:. Search results are tagged
current / unclassified / review / historic / superseded, current first./compact, with one line per other active session on
the same project so parallel agents don't collide.drift reads the wiki and reports what expired, what went silent, what was never written
down and what was left half-done. The current project's top findings go into every session brief.mine reads your local Claude Code transcripts and reports tool usage, failed commands,
re-reads, subagent fan-out and checkpoint discipline. Aggregates only: no prompt, command or
file content is stored or printed, so the digest is safe to paste anywhere.lessons: concepts/ pages with applies_when: [tags]. A project page that lists
matching tags: gets those lessons in its brief, so what worked in one repo reaches the next.
The /retro skill writes them at session end.MCP server (all harnesses): command memory-boost, args ["serve"].
To share one server between several sessions, run it over streamable HTTP (stateless, JSON
responses) and point each harness at http://127.0.0.1:8765/mcp:
It binds to loopback by default and has no authentication: keep it there.
Manual Claude Code hooks (~/.claude/settings.json), not needed with the plugin:
On startup/resume it injects ~1k tokens: catalog, the project's context and last sessions,
its drift, open pending items, lessons from other projects, your open checkpoint. On compact
only this session's checkpoint. It never blocks session start: on any error it prints nothing.
stop and pre-compact write an automatic checkpoint from the transcript, with no LLM call:
your prompts (minus <private>…</private>), files edited and git commits, under the checkpoint's
auto key. What the agent wrote (task, done, next) is never overwritten. stop writes only when
something changed and 10 minutes or 4 prompts passed; pre-compact always writes, so the
post-compact re-injection has something to show even if the agent never called memory_checkpoint.
Skills: /memory-boost (router: when to run what), /save-session, /restore-session,
/retro. The plugin installs them as /memory-boost:retro and so on; without it, copy
skills/* into ~/.claude/skills/. The first session after installing the plugin takes a few
extra seconds while uv fetches memory-boost==0.2.1 and its dependencies from PyPI (the only
network access the plugin makes); later sessions start in about 0.2 s.
CLI contract for agents: data on stdout, errors on stderr with a fix: line, --json on every
reading command (with a version field), exit 0 = trust stdout, 1 = not found, 2 = bad input.
Reports end with a next: line naming the exact command to run.
Source: docs/architecture.mmd
The project is resolved from the working directory name (~/work/acme-api → projects/acme-api.md);
map other names in aliases.json. Under 1,900 lines of Python, one dependency (mcp), no
embeddings unless you opt into semantic recall, no daemon unless you run serve --http.
Every memory_save (or memory-boost save) writes one event to $MEMORY_BOOST_HOME/events/<agent>/<YYYY-MM-DD>.jsonl
and one entry to wiki/log.md. The v2 fields are all optional: a v1 call (project, action, result,
detail, pending as text) keeps working and writes the same log.md header. Each event now carries
"schema": "memory-boost/session@2", a server date_local, a per-session seq and the assigned pending ids;
v1 readers ignore the extra keys.
outcome: done | progress | blocked | waiting | research | abandoned.pending: a list of {text, owner, severity, due?, waiting_on?}. The server assigns each item a stable id
<project>#<n> (counter per project in events/pending-seq.json), shown in the brief under open pending.closes / drops: ids the session finished or no longer needs. Open items are what remains after folding them.session and metrics: optional blocks stored as given. The caller computes them, for example with a
session summary tool; the save itself does not read transcripts.date_local is set by the server from MEMORY_BOOST_TZ (an IANA zone such as Europe/Madrid; UTC by default).
Events written before v2 have no pending ids, so memory-boost pending [--project] (and closes) cannot see them.
Off by default: memory_recall is full-text only and the base install stays one dependency.
To also match paraphrases and other languages, run a local embedding model:
The first index of a large wiki on CPU can take minutes: as a rough guide, about 15 minutes for some
850 documents on a laptop without a GPU (one measurement, not a benchmark). memory-boost index and
recall show embedding N/M chunks… on stderr while it runs; later runs re-embed only what changed.
Default mode when on is hybrid (full-text and vectors fused by weighted reciprocal rank); override
with MEMORY_BOOST_RECALL_MODE=fts|semantic|hybrid or memory-boost recall --mode. If Ollama is down,
recall falls back to full-text and logs a warning. On a private 64-query set (39 literal, 25 paraphrase)
with a warm index on CPU: paraphrase nDCG@10 0.46 to 0.76, literal 0.80 to 0.85, p50 about 110 ms per query.
The query set is not published.
Status values: current, review, historic, superseded; accepted/active read as
current and proposed as review.
Experimental (shipped, little real use yet): memory_shelf, memory-boost friction and the
lesson fields cue/evidence/confidence. Their output format may still change.
Want better search, more integrations and a community? Use basic-memory. Want everything captured automatically? claude-mem. Use memory-boost if you want to learn from what your agents already wrote down.
[semantic] extra and a local Ollama.mine understands Claude Code transcripts today. Codex is on the roadmap.drift.MIT
Source: README.md at commit bf318a4
Cheap orientation (~1k tokens): wiki catalog, the project's stable context and its latest sessions. Call it at the start of a session in harnesses without a SessionStart hook, or to reload a project's context mid-session. `project` is a project name or a directory path.
budgetprojectFull-text search over wiki pages and log entries. Each hit is tagged [kind | date | freshness]; current knowledge is listed before historic and superseded. Historic hits are omitted unless include_historic=true.
limitqueryrequiredprojectinclude_historicRead a wiki page by name (e.g. 'my-api'), or one section of it (a heading or the anchor returned by memory_recall). Prefer this over reading the whole file.
namerequiredsectionRecord what was done in a session: one raw JSONL event plus one compiled entry in wiki/log.md (creates the project page if it does not exist yet). Does not commit to git. action: one line, at most 120 characters. detail: a self-contained paragraph, at most 600 characters; the next session's brief reads it. outcome: done | progress | blocked | waiting | research | abandoned. pending: what is left to do. Either a string split on ';' (each part is the user's, severity 3), or a list of {text, owner, severity, due?, waiting_on?, done_check?} where owner is user | agent | client | third_party, severity is 1-3, due is YYYY-MM-DD, and waiting_on is org:<slug> or person:<slug> when the owner is client or third_party. Severity 1: production down or data loss, a hard deadline within 72 hours, or a client waiting on something that depends on the user. Severity 2: a known open bug, a deadline within 7 days, or an unmitigated risk (exposed secret, work unpushed for more than 3 days). Severity 3: the rest. done_check: how to tell it is finished (a command, or an observable condition); stored and shown, never run. The server assigns each item an id <project>#<n>; the brief shows open items with their ids. closes: ids of open pending items (as shown in the brief) that this session finished. Ids that are unknown, already closed or repeated are not written and come back as `ignored` in the reply. drops: [{id, why}] open pending items that no longer apply. decisions: [{slug, new}] pages in wiki/decisions created or cited. deadlines: [{what, at, hard, pending_ref?}]. orgs: organisations involved that are not the project's client (prospects, suppliers). touches: other project slugs affected. uses: "bip:<capability>" (background IP reused) or "proj:<slug>". billable: whether it counts toward billing a client. money: [{kind, status, ref, amount?, currency?}] with kind quote | invoice | payment | co
orgsusesagentdropsmoneyactionrequiredclosesdetailresultstatedmetricsoutcome+8 moreAppend a dated one-line idea to a wiki page without reading it.
totextrequiredprojectSave this session's working state (a small JSON, no indexing) so it survives context compaction and parallel sessions on the same project can see it. Call it after each milestone: task = current goal (1 line), done = finished steps (accumulated), next_step = the concrete next step, files = files touched. session_id: the `checkpoint_session=` value injected at session start, or any stable id. Set status=done when the session ends (after memory_save).
donetaskrequiredagentfilesnotesstatusprojectrequiredplan_refnext_stepsession_idrequiredReturn this session's checkpoint (if session_id is given) plus one line per other active session on the project. Use after a compaction or when picking up unfinished work; much cheaper than memory_recall.
projectrequiredsession_idWhat in the memory has drifted: decisions past review_by, superseded decisions without a successor, project pages with no session for weeks, busy projects with no recorded decisions, checkpoints left open. Whole wiki, or one project's findings.
projectRecord a lesson that should reach other projects: what worked (or failed), the tools involved and when it applies. `applies_when` are stack/situation tags (e.g. ["fastapi", "celery", "e2e-tests"]); projects whose page lists matching `tags:` get this lesson in their session brief. `learned_on` = this project's slug. cue: the shape of situation it fires on (the pattern, not this task's facts). evidence: the observed contrast it rests on (before/after, A vs B, with numbers or the moment it diverged); "it looked like good practice" is not evidence. confidence: high | medium | low, only with evidence. If nothing observed supports a transferable lesson, do not record one: no lesson is a valid outcome.
cuebodyrequirednamerequiredtitlerequiredevidenceconfidencelearned_onapplies_whenrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
fit.memoryOfficial publisher
Hosted Memory.fit server that lets an AI read your training, sleep, recovery and nutrition data and write back weekly plans, targets and meal plans.
io.ddx.pgOfficial publisher
pg.ddx.io: the PostgreSQL community's memory's hosted MCP server, published by pg.ddx.io; no sign-in required; Streamable HTTP; 29 tools.
gg.varOfficial publisher
Remote MCP server that suggests and searches code identifier names from domain concepts in Korean, Japanese, Chinese, Vietnamese and English, and exposes ERD…
Published by GitHub account kolivritech
Remote MCP server giving AI coding agents deterministic long-term memory plus code intelligence tools, with no LLM tokens spent on recall.
Published by GitHub account jacobbarglof
Gives every MCP-capable AI app one shared, private memory of plain note pages that assistants can search, read and update.
uvx memory-boost==0.2.1 init --example # sample wiki with five kinds of rot + four synthetic transcriptsuvx memory-boost==0.2.1 drift # what in that memory is stale, orphaned or never written downuvx memory-boost==0.2.1 mine # now on your real ~/.claude/projects: aggregates only/plugin marketplace add arnaugonzalez/memory-boost/plugin install memory-boost@memory-boost$ memory-boost drift# Drift report — 2026-09-2429 decisions · 24 projects · 204 log entries · 33 open checkpoints · **20 findings**
## decision-expired (9)- deploy-via-bastion — review_by 2026-07-08 (78 days ago); revisit or mark historic- bot-guardrails — review_by 2026-07-08 (78 days ago); revisit or mark historic …## project-no-decisions (2)- thesis-solver — 20 sessions logged, 0 decisions tagged 'thesis-solver': the learning lives only in transcripts## project-silent (5)- mood-api — last session 2026-04-16 (161 days ago); still listed as live …
$ memory-boost mine# Session digest — 2026-09-24sessions 80 with ≥20 turnstools Bash 5956 · Edit 860 · Read 692 · Write 493 · Agent 203 · ToolSearch 138bash 5956 calls, 159 failed (2.7%); most failed: cd (69), sleep (12), ssh (9), pkill (8), ls (7)bash/edit 4.4x; extreme: worktree-a 107.5x, sandbox 70.0x, sandbox 54.0xreads 692 calls, 131 re-reads of a file already read (19%); top: …/apply_email.py ×18discipline 62 long sessions (≥60 turns): 47 never checkpointed, 29 never savedsubagents 203 spawned in 44 sessions; max in one session: 20memory-boost serve --http # --host 127.0.0.1 --port 8765 are the defaultsclaude mcp add --transport http memory -s user http://127.0.0.1:8765/mcp{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memory-boost hook session-start" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "memory-boost hook stop", "timeout": 10 } ] } ], "PreCompact": [ { "hooks": [ { "type": "command", "command": "memory-boost hook pre-compact", "timeout": 20 } ] } ]} }{ "schema": "memory-boost/session@2", "project": "acme-api", "action": "Moved the job queue to Postgres and added retries", "result": "ok", "outcome": "progress", "session": {"id": "3f9c2a1e-…", "harness": "claude-code", "cwd": "/home/me/work/acme-api", "segment_start": "2026-10-28T10:00:03Z", "segment_end": "2026-10-28T14:45:12Z"}, "metrics": {"source": "ledger session-summary@1", "minutes": {"acme-api": {"attention": 182, "agent": 160, "gross": 230}}, "commits": [{"repo": "acme-api", "sha": "f2c1114", "pushed": false}], "tests": {"runs": 6, "passed": 1180, "failed": 0}, "cost_usd": 14.2}, "pending": [{"text": "Run the batch import", "owner": "user", "severity": 3}, {"text": "Push main to origin", "owner": "user", "severity": 2}], "closes": ["acme-api#12", "acme-api#14"]}pip install "memory-boost[semantic]==0.2.1" # adds sqlite-vecollama pull embeddinggemmaexport MEMORY_BOOST_SEMANTIC=1memory-boost index # embeds the wiki once; later runs embed only changes