memory-boost 0.1.0__py3-none-any.whl

memory_boost/server.py

@@ -0,0 +1,102 @@
+"""MCP server (stdio) exposing the memory as eight tools. Run: `memory-boost serve`."""
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from memory_boost import core, drift, lessons
+
+mcp = FastMCP("memory")
+
+
+@mcp.tool()
+def memory_brief(project: str | None = None, budget: int = 1200) -> str:
+    """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."""
+    return core.brief(project, budget=budget)["text"]
+
+
+@mcp.tool()
+def memory_recall(query: str, project: str | None = None, limit: int = 8,
+                  include_historic: bool = False) -> str:
+    """Full-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."""
+    results = core.recall(query, project=project, limit=limit, include_historic=include_historic)
+    if not results:
+        return "(no results)"
+    lines = [f"[{r['kind']} | {r['date'] or '?'} | {r['freshness']}] {r['ref']} — {r['extract']}"
+             for r in results]
+    lines.append("\n> Read a whole section with memory_page(name, section)")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def memory_page(name: str, section: str | None = None) -> str:
+    """Read 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."""
+    return core.get_page(name, section)
+
+
+@mcp.tool()
+def memory_save(project: str, action: str, detail: str | None = None, result: str = "ok",
+                agent: str = "mcp", pending: str | None = None) -> str:
+    """Record 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). `action` is a
+    one-line summary; `detail` a longer bullet; `pending` what is left to do.
+    Does not commit anything to git."""
+    slug = core.save(project, action, detail=detail, result=result, agent=agent, pending=pending)
+    return f"saved: {slug} | {action}"
+
+
+@mcp.tool()
+def memory_checkpoint(project: str, session_id: str, task: str, done: list[str] | None = None,
+                      next_step: str | None = None, files: list[str] | None = None,
+                      notes: list[str] | None = None, status: str = "active",
+                      plan_ref: str | None = None, agent: str = "agent") -> str:
+    """Save 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)."""
+    c = core.save_checkpoint(project, session_id, task, agent=agent, done=done,
+                             next_step=next_step, files=files, notes=notes, status=status,
+                             plan_ref=plan_ref)
+    return f"checkpoint: {c['project']} | {session_id} | {c['status']} | done={len(c['done'])}"
+
+
+@mcp.tool()
+def memory_resume(project: str, session_id: str | None = None) -> str:
+    """Return 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."""
+    return core.resume_text(project, session_id)
+
+
+@mcp.tool()
+def memory_drift(project: str | None = None) -> str:
+    """What 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."""
+    report = drift.drift_report()
+    if project:
+        lines = drift.for_project(project, n=20)
+        return "\n".join(lines) if lines else f"(nothing drifted for {core.norm_project(project)})"
+    return drift.format_report(report)
+
+
+@mcp.tool()
+def memory_lesson(name: str, title: str, applies_when: list[str], body: str,
+                  learned_on: str | None = None) -> str:
+    """Record 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."""
+    p = lessons.save_lesson(name, title, applies_when, body, learned_on=learned_on)
+    return f"lesson saved: {p.name} (applies_when: {', '.join(sorted(set(applies_when)))})"
+
+
+def main() -> None:
+    mcp.run()

memory_boost-0.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: memory-boost
+Version: 0.1.0
+Summary: Memory that reviews itself: a markdown wiki for coding agents over MCP, plus drift reports on the wiki and digests of your own sessions.
+Project-URL: Repository, https://github.com/arnaugonzalez/memory-boost
+Project-URL: Issues, https://github.com/arnaugonzalez/memory-boost/issues
+Project-URL: Changelog, https://github.com/arnaugonzalez/memory-boost/blob/main/CHANGELOG.md
+Author: Arnau González
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,llm,mcp,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.arnaugonzalez/memory-boost -->
+<h1 align="center">memory-boost</h1>
+
+<p align="center"><em>Memory for coding agents that reviews itself.</em></p>
+
+<p align="center">
+  <a href="https://github.com/arnaugonzalez/memory-boost/actions/workflows/ci.yml"><img src="https://github.com/arnaugonzalez/memory-boost/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT">
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
+</p>
+
+<p align="center">
+  <img src="docs/demo.gif" alt="memory-boost drift, mine and lessons running on the bundled example data" width="92%"><br>
+  <sub>drift, mine and lessons on the bundled example data · everything runs locally</sub>
+</p>
+
+<p align="center">
+  <a href="#try-it-in-30-seconds">Try it</a> ·
+  <a href="#what-it-answers">What it answers</a> ·
+  <a href="#connect-your-harness">Connect your agent</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#vs-alternatives">vs. alternatives</a>
+</p>
+
+**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.
+
+## What it answers
+
+| You wonder… | memory-boost answers |
+|---|---|
+| Which decisions quietly expired while we were busy shipping? | `drift`: *review_by 2026-07-08, 78 days ago* |
+| Which "active" projects actually died months ago? | `drift`: *last session 161 days ago; still listed as live* |
+| We fixed this exact bug in another repo. How? | `lessons`: the fix follows you to every project with the same stack |
+| Why does my agent keep re-reading the same file? | `mine`: *one file, read 18 times* |
+| Is my agent spawning 20 subagents behind my back? | `mine`: yes, and in which session |
+| Where was I before `/compact` ate my context? | The session-start hook puts your checkpoint back |
+
+## Try it in 30 seconds
+
+No install needed; the wiki lands in `~/.local/share/memory-boost`:
+
+```bash
+uvx memory-boost init --example   # sample wiki with five kinds of rot + four synthetic transcripts
+uvx memory-boost drift            # what in that memory is stale, orphaned or never written down
+uvx memory-boost mine             # now on your real ~/.claude/projects: aggregates only
+```
+
+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](https://docs.astral.sh/uv/) on your PATH.
+
+```
+/plugin marketplace add arnaugonzalez/memory-boost
+/plugin install memory-boost@memory-boost
+```
+
+Other agents, or the CLI on its own: `uv tool install memory-boost` (or `pipx install memory-boost`).
+
+## On a real machine
+
+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.
+
+```
+$ memory-boost drift
+# Drift report — 2026-09-24
+29 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-24
+sessions      80 with ≥20 turns
+tools         Bash 5956 · Edit 860 · Read 692 · Write 493 · Agent 203 · ToolSearch 138
+bash          5956 calls, 159 failed (2.7%); most failed: cd (69), sleep (12), ssh (9), pkill (8), ls (7)
+bash/edit     4.4x; extreme: crm-wt-f11 107.5x, sandbox 70.0x, sandbox 54.0x
+reads         692 calls, 131 re-reads of a file already read (19%); top: …/apply_email.py ×18
+discipline    62 long sessions (≥60 turns): 47 never checkpointed, 29 never saved
+subagents     203 spawned in 44 sessions; max in one session: 20
+```
+
+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.
+
+## What it is
+
+1. **A wiki you own.** `projects/*.md`, `decisions/*.md`, `concepts/*.md`, `log.md`. Plain
+   markdown; edit by hand, keep it in git. SQLite FTS5 index as a disposable cache. Eight MCP
+   tools for any harness: `memory_brief`, `memory_recall`, `memory_page`, `memory_save`,
+   `memory_checkpoint`, `memory_resume`, `memory_drift`, `memory_lesson`.
+2. **Freshness as data.** Decisions carry `status:` and `review_by:`. Search results are tagged
+   `current / unclassified / review / historic / superseded`, current first.
+3. **Session checkpoints** that survive `/compact`, with one line per *other* active session on
+   the same project so parallel agents don't collide.
+4. **`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.
+5. **`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.
+6. **`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.
+
+## Connect your harness
+
+MCP server (all harnesses): command `memory-boost`, args `["serve"]`.
+
+| Harness | MCP registration | Context at session start |
+|---|---|---|
+| Claude Code (plugin) | `/plugin install memory-boost@memory-boost` | Included: hook, MCP server, skills |
+| Claude Code (manual) | `claude mcp add memory -s user -- memory-boost serve` | Hook below (startup, resume, compact); `mine` reads its transcripts |
+| Codex CLI | `codex mcp add memory -- memory-boost serve` | `AGENTS.md`: "call `memory_brief` first" |
+| Cursor / VS Code / Gemini CLI | stdio entry in their `mcp.json` / `settings.json` | Same line in rules (hook adapters: roadmap) |
+
+Manual Claude Code hook (`~/.claude/settings.json`), not needed with the plugin:
+
+```json
+{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memory-boost hook session-start" } ] } ] } }
+```
+
+On `startup`/`resume` it injects ~1k tokens: catalog, the project's context and last sessions,
+its drift, 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.
+
+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 the package; 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.
+
+## How it works
+
+```mermaid
+flowchart LR
+  A[Claude Code / Codex / Cursor] -->|MCP stdio| S[memory-boost serve]
+  H[SessionStart hook] --> B[memory-boost hook]
+  S --> W[(wiki/*.md + log.md)]
+  S --> K[(checkpoints/*.json)]
+  D[memory-boost drift] --> W
+  D --> K
+  M[memory-boost mine] --> T[(~/.claude/projects/*.jsonl)]
+  D --> R[report + brief injection]
+  M --> R
+  W -.incremental refresh.-> I[(SQLite FTS5)]
+```
+
+The project is resolved from the working directory name (`~/work/acme-api` → `projects/acme-api.md`);
+map other names in `aliases.json`. Under 1,600 lines of Python, one dependency (`mcp`), no
+embeddings, no daemon.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MEMORY_BOOST_HOME` | `$XDG_DATA_HOME/memory-boost` | Wiki, events, checkpoints, `aliases.json` |
+| `MEMORY_BOOST_WIKI` | `$MEMORY_BOOST_HOME/wiki` | Point at an existing wiki (e.g. a git repo) |
+| `MEMORY_BOOST_INDEX` | `$XDG_CACHE_HOME/memory-boost/index-<hash>.db` | Search index |
+| `MEMORY_BOOST_CHECKPOINTS` | `$MEMORY_BOOST_HOME/checkpoints` | Checkpoint directory |
+| `MEMORY_BOOST_TRANSCRIPTS` | `~/.claude/projects` | Where `mine` looks (several dirs: `a:b`) |
+| `MEMORY_BOOST_TODAY` | today (UTC) | Pin the date for reproducible reports |
+
+## vs. alternatives
+
+| | memory-boost | [basic-memory](https://github.com/basicmachines-co/basic-memory) | [claude-mem](https://github.com/thedotmack/claude-mem) | [agent-retro](https://github.com/giannimassi/agent-retro) |
+|---|---|---|---|---|
+| Store | Markdown wiki you edit | Markdown | Captured observations | None (prompt skill) |
+| Search | FTS5 | FTS + vectors | FTS + vectors | — |
+| Freshness / review dates | Yes | No | No | — |
+| Drift report over memory | Yes | No | No | No |
+| Session analytics | Yes (aggregates, local) | No | No | LLM reads the conversation |
+| Parallel-session awareness | Yes | No | No | — |
+| License | MIT | AGPL-3.0 | Apache-2.0 | ? |
+
+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.
+
+## Limits / non-goals
+
+- Keyword search only; no embeddings.
+- `mine` understands Claude Code transcripts today. Codex is on the roadmap.
+- Reports are as good as the wiki: an empty wiki yields an empty `drift`.
+- Single user, local files. Linux and macOS; Windows untested.
+- The wiki is read by your agents as instructions. Only use a wiki you trust; see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

memory_boost-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+memory_boost/__init__.py,sha256=x4SbW6W2VAjRLLAZ5V-EIvEb5yLkqljlC66g4MHnhGs,101
+memory_boost/cli.py,sha256=Z158TZjAPJE9wZYB8zwPm-jcFfFZjFwVuqfT5fFsM5c,17354
+memory_boost/core.py,sha256=m0NTI4xbjoMzmj0EfZiadJnYL5cN0uo18H7ha7afSdI,27980
+memory_boost/drift.py,sha256=6eGmlnaHtSKuAzT4f9J_5oP2cnbSN5MHsB1UIHcnipE,7357
+memory_boost/lessons.py,sha256=3wWB_azov5gpd4myOwY5apqtoU4paBix251wKeFBkC8,3452
+memory_boost/mine.py,sha256=Xe_wIIYuEwvNbm6qS6zopMJGK9ZDRGgNk6l8T81mM2I,8406
+memory_boost/server.py,sha256=bElZH0aaEfUDvi1CpcpchT64wS97WXrjkZ0EX2TjKIQ,5095
+memory_boost/example_transcripts/-work-acme-api/0a1b2c3d-1111-4aaa-8bbb-000000000001.jsonl,sha256=LD5HvJRXIMRqfrIWmjdZdb1ctExaY0AhpEaK0_qjXBI,40158
+memory_boost/example_transcripts/-work-acme-api/0a1b2c3d-3333-4aaa-8bbb-000000000003.jsonl,sha256=LIgPIaoCJX3Pl5H2OztYiT6nE_QHrWYEIzCtzcyB-1k,14199
+memory_boost/example_transcripts/-work-acme-api/0a1b2c3d-4444-4aaa-8bbb-000000000004.jsonl,sha256=KaIR7U8whyGjFcj26pyrfo1VAF25Qo8dR_SUjTzPNGY,2914
+memory_boost/example_transcripts/-work-pixel-notes/0a1b2c3d-2222-4aaa-8bbb-000000000002.jsonl,sha256=wdbZfBSeYzI22JX2ViNPfv-cYOScN3cbj6vbE2PTUGY,16718
+memory_boost/example_wiki/log.md,sha256=lJ7M0QcHm3V1FrLk9ccadyz9TGSl4EfYNawBFhd9z10,1569
+memory_boost/example_wiki/concepts/money-as-integer-cents.md,sha256=ElENsKlRweJX7tIYgNP0EhYPYOZd363CVqKbr3kdC7I,572
+memory_boost/example_wiki/concepts/retry-jobs-idempotently.md,sha256=RxD23e8VDAMh-AnW4DKoF5xP_qPnachnZ_AMPGaS0lw,677
+memory_boost/example_wiki/context/preferences.md,sha256=efVSlBi-ObOLIt2RR91ZrcSwfWkkV9xKuFqXRGDjmSE,145
+memory_boost/example_wiki/decisions/cors-allow-all.md,sha256=0vvXvnZcx9dD1VHyIuI_zYBelnHyczchV8Ole8yyO40,278
+memory_boost/example_wiki/decisions/float-money.md,sha256=auJCbLXid1uWvEF6XNLeQB4Wo2E7aZqfSD5MQGMEhK0,180
+memory_boost/example_wiki/decisions/pin-postgres-15.md,sha256=WfzKqy0mz98AmoVwtTX2WphIeaOmdnKxaacsBoOu6cU,477
+memory_boost/example_wiki/decisions/queue-in-postgres.md,sha256=3Lx9uu8FBWzDWS-HfmMGR0wpWdk7PZX66lwgzhubMGA,293
+memory_boost/example_wiki/decisions/sessions-in-redis.md,sha256=uQ3YXi22QmOjRm_Alq9GBR8LEH8JvvpXRGD3NR6hIpA,179
+memory_boost/example_wiki/projects/acme-api.md,sha256=kW_s1p8R93A5DPONfst85s7ulAAO-6qSNzXmbCpUU5w,694
+memory_boost/example_wiki/projects/legacy-dashboard.md,sha256=rkVLTGeONq0oAEWn1ubR5J_m4tz8TuwM-I40i-4ggwk,311
+memory_boost/example_wiki/projects/pixel-notes.md,sha256=1y8ej-vPQhC4T2YD_ARDxIq_VLSbF3k7g3WW5Ecge8I,269
+memory_boost-0.1.0.dist-info/METADATA,sha256=WXaSlMg7eQMI_XdXrIsejDq9CASLeButtln92cExHLg,11374
+memory_boost-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+memory_boost-0.1.0.dist-info/entry_points.txt,sha256=5_mus1iRcuFD2AFj8SHImnu4gvZlqDA4QWiW3XLcfiQ,55
+memory_boost-0.1.0.dist-info/licenses/LICENSE,sha256=Oig0c4XeN86DBcOVv-Yl4ImWuWYARgDw0oxNljnRwlI,1072
+memory_boost-0.1.0.dist-info/RECORD,,

memory_boost-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

memory_boost-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memory-boost = memory_boost.cli:main

memory_boost-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnau González
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.