foldcrumbs 0.3.0__tar.gz

foldcrumbs-0.3.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Vincenzo Ingrosso
+
+Portions of this software (typed-memory schema and trust/decay logic,
+extraction prompts and parser, lifecycle-hook plumbing, and context-block
+rendering) are derived from MEMANTO (https://github.com/moorcheh-ai/memanto),
+Copyright (c) Moorcheh / Edge AI Innovations, licensed under the MIT License.
+
+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.

foldcrumbs-0.3.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: foldcrumbs
+Version: 0.3.0
+Summary: Persistent cross-session memory for coding agents — file-based, no vector DB, no external service.
+Author: Vincenzo Ingrosso
+License: MIT
+Project-URL: Repository, https://github.com/vcnngr/foldcrumbs
+Keywords: claude-code,codex,opencode,agent-memory,llm,hooks,mlx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# foldcrumbs
+
+[![tests](https://github.com/vcnngr/foldcrumbs/actions/workflows/test.yml/badge.svg)](https://github.com/vcnngr/foldcrumbs/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Persistent cross-session memory for coding agents — **no Docker, no vector DB, no external service**.
+
+`/clear` and compaction wipe Claude Code's knowledge every session. foldcrumbs keeps a small
+folder of typed memory files so the agent reopens already knowing your decisions, conventions
+and codebase facts. It also fights context rot: around 45% context it checkpoints memory in the
+background and nudges you to `/compact` or `/clear` — nothing is lost.
+
+## How it works
+
+```
+STORE     markdown files + MEMORY.md index in
+          ~/.claude/projects/<project>/memory/
+RECALL    Claude Code's own Grep/Read (no LLM, no vector DB)
+          + SessionStart injects the index
+DISTILL   async, local LLM only (MLX/Ollama/OpenRouter via env)
+          at ~45% context and at session end → gated, dedup'd
+ANTI-ROT  PostToolUse monitor → checkpoint + reminder (no forced compaction)
+          PostCompact → re-inject index after compaction
+HANDOFF   each checkpoint also writes a live working-state snapshot, re-injected
+          at SessionStart → resume the exact task after a /clear
+```
+
+The retrieval engine is the agent itself: it greps the folder when relevant. The LLM is used
+**only** for async distillation — so recall is instant and never depends on a model being up.
+
+Pure Python stdlib: hook scripts never fail on a missing import.
+
+The `MEMORY.md` index is written in a **deterministic order** (by immutable
+creation time, newest first within each type), so a trust bump, re-touch or
+re-distillation never reshuffles existing entries. Only adding or removing a
+memory changes the file. This keeps the SessionStart-injected prefix identical
+across sessions — so it rides the agent's own prompt cache instead of busting it
+— and keeps the file diff-clean for sync tools like Syncthing.
+
+## What's different from memanto
+
+foldcrumbs started from ideas in [memanto](https://github.com/moorcheh-ai/memanto), but takes a
+deliberately different shape:
+
+| | memanto | foldcrumbs |
+|--|--|--|
+| Retrieval | Moorcheh engine (closed) | the agent's own grep — no engine |
+| Footprint | Docker + engine + LLM + REST API | a folder + hooks |
+| LLM | required for retrieval & answers | async distillation only; recall never needs it |
+| Anti-rot | — | context monitor + checkpoint near 45% |
+| Deps | service stack | zero runtime deps (stdlib) |
+| Scope | tool-agnostic service | per-project memory, agent-side |
+
+The original work here is the architecture: grep-based recall, the file store + index, the
+anti-rot monitor, the merge-safe installer, the hooks and CLI. See **Credits** for the parts
+adapted from memanto.
+
+## Install
+
+```bash
+foldcrumbs install                      # Claude Code, global (~/.claude/settings.json)
+foldcrumbs install --local              # Claude Code, project (.claude/settings.json)
+foldcrumbs install --agent codex        # Codex: hooks.json + prints the config.toml MCP snippet
+foldcrumbs install --agent opencode     # OpenCode: opencode.json MCP + plugin + AGENTS.md block
+```
+The installer is merge-safe and idempotent: it appends its own hook groups and leaves existing
+hooks (GSD, graphify, …) untouched. A `.foldcrumbs-bak` backup is written first.
+
+On a TTY, install asks **how to distill** (recall never uses an LLM):
+
+```
+1) claude-cli   Claude subscription — `claude -p`, no API key
+2) codex        Codex subscription — `codex exec`, no API key
+3) openai       OpenAI-compatible HTTP endpoint (local server or remote gateway)
+4) none         no LLM — keyword heuristic only (last resort)
+```
+
+The choice is saved per-machine in `~/.foldcrumbs` (not synced), so a shared store can have one
+indexer with a local model and others using their own CLI subscription. Skip the prompt with
+`foldcrumbs install --backend codex` (or `--no-backend-prompt`), and change it anytime with
+`foldcrumbs backend <name>` (`foldcrumbs backend` alone shows the current one).
+
+All agents share **one** memory store per project, so a decision recorded in Claude Code is
+recalled in Codex and OpenCode.
+
+## Configure (env)
+
+| var | default | meaning |
+|-----|---------|---------|
+| `FOLDCRUMBS_LLM_ENDPOINT` | `http://localhost:8081` | OpenAI-compatible endpoint (MLX server) |
+| `FOLDCRUMBS_LLM_MODEL` | `gemma-4-26b-a4b` | model name |
+| `FOLDCRUMBS_LLM_API_KEY` | – | optional bearer token |
+| `FOLDCRUMBS_CONTEXT_BUDGET` | `200000` | context window size (tokens) for the monitor |
+| `FOLDCRUMBS_CONTEXT_PCT` | `0.45` | fraction at which to checkpoint + nudge |
+| `FOLDCRUMBS_MIN_CONFIDENCE` | `0.7` | write gate floor |
+| `FOLDCRUMBS_DIR` | derived from cwd | override the memory directory |
+
+Swap the LLM for a remote gateway or OpenRouter by changing `FOLDCRUMBS_LLM_ENDPOINT` — recall is
+unaffected.
+
+## CLI
+
+```bash
+python3 -m foldcrumbs status
+python3 -m foldcrumbs remember "Recall is grep, no vector DB" --type decision --tag arch
+python3 -m foldcrumbs recall "vector db"
+python3 -m foldcrumbs index
+python3 -m foldcrumbs distill transcript.txt    # distil durable memories (LLM)
+python3 -m foldcrumbs checkpoint transcript.txt # write a resume handoff (LLM)
+python3 -m foldcrumbs handoff                   # print the current handoff
+python3 -m foldcrumbs answer "how does recall work?"
+```
+
+## Surviving `/clear` and `/compact`
+
+Two layers cross the context switch:
+
+- **Durable memories** (decisions, rules, preferences, facts) — always re-injected via
+  the `MEMORY.md` index at SessionStart / PostCompact.
+- **Working-state handoff** — a single overwritten snapshot of the *current* task, files
+  in flight and next steps, written at each checkpoint and re-injected so you resume the
+  exact task after a hard `/clear`.
+
+At ~45% context foldcrumbs nudges you; pick `/compact` (keep working) or `/clear` (fresh start) —
+either way the next turn is re-primed. Force a snapshot anytime with `foldcrumbs checkpoint`.
+
+## Local LLM
+
+Distillation needs any OpenAI-compatible chat endpoint — point `FOLDCRUMBS_LLM_ENDPOINT`
+at whatever you run. It's used only for async distillation, so a cold model load is
+invisible to the editor, and **recall needs no model at all**.
+
+Common local servers (all expose `/v1/chat/completions`):
+
+```bash
+# MLX — Apple Silicon only, fastest on Mac
+mlx_lm.server  --model <gemma-mlx-repo> --port 8081     # or mlx_vlm.server for VLMs
+
+# Ollama — cross-platform (macOS / Linux / Windows)
+ollama serve                                            # endpoint :11434/v1
+
+# llama.cpp / LM Studio / vLLM — also OpenAI-compatible
+```
+
+Then e.g. `export FOLDCRUMBS_LLM_ENDPOINT=http://localhost:11434 FOLDCRUMBS_LLM_MODEL=qwen2.5`.
+A remote gateway or OpenRouter works the same way — only the env var changes.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## MCP server
+
+foldcrumbs ships a minimal MCP server (stdio, stdlib only — no `mcp` SDK dependency) exposing
+`remember`, `recall` and `answer` to any MCP client:
+
+```bash
+foldcrumbs-mcp            # or: python3 -m foldcrumbs.mcp_server
+```
+Codex and OpenCode are wired to it by `foldcrumbs install --agent …`. Use it directly from any
+MCP-speaking tool by registering the command above.
+
+## How each agent is wired
+
+| Agent | Inject at start | Capture | Notes |
+|-------|-----------------|---------|-------|
+| Claude Code | SessionStart hook | PostToolUse monitor + SessionEnd | full lifecycle hooks |
+| Codex | SessionStart hook (`additionalContext`) | Stop + PostToolUse hooks | same scripts; + MCP for in-session tool calls |
+| OpenCode | AGENTS.md → agent calls `recall` (MCP) | plugin `session.idle`/`session.compacted` | no inject-capable hook, so prompt-driven recall |
+
+## Roadmap
+
+- **Phase 1 ✓** — Claude Code: file store, grep recall, distillation, anti-rot.
+- **Phase 2 ✓** — Codex + OpenCode on the same store via a stdlib MCP server + installers.
+- **Phase 3** — embeddings + open vector DB only if scale outgrows grep; document ingest via OCR.
+
+## Credits
+
+foldcrumbs adapts a few utilities from [memanto](https://github.com/moorcheh-ai/memanto)
+(MIT, © Moorcheh / Edge AI Innovations): the typed-memory categories and confidence/decay
+model, the session-distillation approach, the transcript-reading helper, and the context-block
+rendering idea. These are reimplemented here against a file store; the Moorcheh retrieval engine
+is not used. Full notice in [LICENSE](LICENSE). Thanks to the memanto authors for releasing it
+under MIT.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

foldcrumbs-0.3.0/README.md

@@ -0,0 +1,190 @@
+# foldcrumbs
+
+[![tests](https://github.com/vcnngr/foldcrumbs/actions/workflows/test.yml/badge.svg)](https://github.com/vcnngr/foldcrumbs/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Persistent cross-session memory for coding agents — **no Docker, no vector DB, no external service**.
+
+`/clear` and compaction wipe Claude Code's knowledge every session. foldcrumbs keeps a small
+folder of typed memory files so the agent reopens already knowing your decisions, conventions
+and codebase facts. It also fights context rot: around 45% context it checkpoints memory in the
+background and nudges you to `/compact` or `/clear` — nothing is lost.
+
+## How it works
+
+```
+STORE     markdown files + MEMORY.md index in
+          ~/.claude/projects/<project>/memory/
+RECALL    Claude Code's own Grep/Read (no LLM, no vector DB)
+          + SessionStart injects the index
+DISTILL   async, local LLM only (MLX/Ollama/OpenRouter via env)
+          at ~45% context and at session end → gated, dedup'd
+ANTI-ROT  PostToolUse monitor → checkpoint + reminder (no forced compaction)
+          PostCompact → re-inject index after compaction
+HANDOFF   each checkpoint also writes a live working-state snapshot, re-injected
+          at SessionStart → resume the exact task after a /clear
+```
+
+The retrieval engine is the agent itself: it greps the folder when relevant. The LLM is used
+**only** for async distillation — so recall is instant and never depends on a model being up.
+
+Pure Python stdlib: hook scripts never fail on a missing import.
+
+The `MEMORY.md` index is written in a **deterministic order** (by immutable
+creation time, newest first within each type), so a trust bump, re-touch or
+re-distillation never reshuffles existing entries. Only adding or removing a
+memory changes the file. This keeps the SessionStart-injected prefix identical
+across sessions — so it rides the agent's own prompt cache instead of busting it
+— and keeps the file diff-clean for sync tools like Syncthing.
+
+## What's different from memanto
+
+foldcrumbs started from ideas in [memanto](https://github.com/moorcheh-ai/memanto), but takes a
+deliberately different shape:
+
+| | memanto | foldcrumbs |
+|--|--|--|
+| Retrieval | Moorcheh engine (closed) | the agent's own grep — no engine |
+| Footprint | Docker + engine + LLM + REST API | a folder + hooks |
+| LLM | required for retrieval & answers | async distillation only; recall never needs it |
+| Anti-rot | — | context monitor + checkpoint near 45% |
+| Deps | service stack | zero runtime deps (stdlib) |
+| Scope | tool-agnostic service | per-project memory, agent-side |
+
+The original work here is the architecture: grep-based recall, the file store + index, the
+anti-rot monitor, the merge-safe installer, the hooks and CLI. See **Credits** for the parts
+adapted from memanto.
+
+## Install
+
+```bash
+foldcrumbs install                      # Claude Code, global (~/.claude/settings.json)
+foldcrumbs install --local              # Claude Code, project (.claude/settings.json)
+foldcrumbs install --agent codex        # Codex: hooks.json + prints the config.toml MCP snippet
+foldcrumbs install --agent opencode     # OpenCode: opencode.json MCP + plugin + AGENTS.md block
+```
+The installer is merge-safe and idempotent: it appends its own hook groups and leaves existing
+hooks (GSD, graphify, …) untouched. A `.foldcrumbs-bak` backup is written first.
+
+On a TTY, install asks **how to distill** (recall never uses an LLM):
+
+```
+1) claude-cli   Claude subscription — `claude -p`, no API key
+2) codex        Codex subscription — `codex exec`, no API key
+3) openai       OpenAI-compatible HTTP endpoint (local server or remote gateway)
+4) none         no LLM — keyword heuristic only (last resort)
+```
+
+The choice is saved per-machine in `~/.foldcrumbs` (not synced), so a shared store can have one
+indexer with a local model and others using their own CLI subscription. Skip the prompt with
+`foldcrumbs install --backend codex` (or `--no-backend-prompt`), and change it anytime with
+`foldcrumbs backend <name>` (`foldcrumbs backend` alone shows the current one).
+
+All agents share **one** memory store per project, so a decision recorded in Claude Code is
+recalled in Codex and OpenCode.
+
+## Configure (env)
+
+| var | default | meaning |
+|-----|---------|---------|
+| `FOLDCRUMBS_LLM_ENDPOINT` | `http://localhost:8081` | OpenAI-compatible endpoint (MLX server) |
+| `FOLDCRUMBS_LLM_MODEL` | `gemma-4-26b-a4b` | model name |
+| `FOLDCRUMBS_LLM_API_KEY` | – | optional bearer token |
+| `FOLDCRUMBS_CONTEXT_BUDGET` | `200000` | context window size (tokens) for the monitor |
+| `FOLDCRUMBS_CONTEXT_PCT` | `0.45` | fraction at which to checkpoint + nudge |
+| `FOLDCRUMBS_MIN_CONFIDENCE` | `0.7` | write gate floor |
+| `FOLDCRUMBS_DIR` | derived from cwd | override the memory directory |
+
+Swap the LLM for a remote gateway or OpenRouter by changing `FOLDCRUMBS_LLM_ENDPOINT` — recall is
+unaffected.
+
+## CLI
+
+```bash
+python3 -m foldcrumbs status
+python3 -m foldcrumbs remember "Recall is grep, no vector DB" --type decision --tag arch
+python3 -m foldcrumbs recall "vector db"
+python3 -m foldcrumbs index
+python3 -m foldcrumbs distill transcript.txt    # distil durable memories (LLM)
+python3 -m foldcrumbs checkpoint transcript.txt # write a resume handoff (LLM)
+python3 -m foldcrumbs handoff                   # print the current handoff
+python3 -m foldcrumbs answer "how does recall work?"
+```
+
+## Surviving `/clear` and `/compact`
+
+Two layers cross the context switch:
+
+- **Durable memories** (decisions, rules, preferences, facts) — always re-injected via
+  the `MEMORY.md` index at SessionStart / PostCompact.
+- **Working-state handoff** — a single overwritten snapshot of the *current* task, files
+  in flight and next steps, written at each checkpoint and re-injected so you resume the
+  exact task after a hard `/clear`.
+
+At ~45% context foldcrumbs nudges you; pick `/compact` (keep working) or `/clear` (fresh start) —
+either way the next turn is re-primed. Force a snapshot anytime with `foldcrumbs checkpoint`.
+
+## Local LLM
+
+Distillation needs any OpenAI-compatible chat endpoint — point `FOLDCRUMBS_LLM_ENDPOINT`
+at whatever you run. It's used only for async distillation, so a cold model load is
+invisible to the editor, and **recall needs no model at all**.
+
+Common local servers (all expose `/v1/chat/completions`):
+
+```bash
+# MLX — Apple Silicon only, fastest on Mac
+mlx_lm.server  --model <gemma-mlx-repo> --port 8081     # or mlx_vlm.server for VLMs
+
+# Ollama — cross-platform (macOS / Linux / Windows)
+ollama serve                                            # endpoint :11434/v1
+
+# llama.cpp / LM Studio / vLLM — also OpenAI-compatible
+```
+
+Then e.g. `export FOLDCRUMBS_LLM_ENDPOINT=http://localhost:11434 FOLDCRUMBS_LLM_MODEL=qwen2.5`.
+A remote gateway or OpenRouter works the same way — only the env var changes.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## MCP server
+
+foldcrumbs ships a minimal MCP server (stdio, stdlib only — no `mcp` SDK dependency) exposing
+`remember`, `recall` and `answer` to any MCP client:
+
+```bash
+foldcrumbs-mcp            # or: python3 -m foldcrumbs.mcp_server
+```
+Codex and OpenCode are wired to it by `foldcrumbs install --agent …`. Use it directly from any
+MCP-speaking tool by registering the command above.
+
+## How each agent is wired
+
+| Agent | Inject at start | Capture | Notes |
+|-------|-----------------|---------|-------|
+| Claude Code | SessionStart hook | PostToolUse monitor + SessionEnd | full lifecycle hooks |
+| Codex | SessionStart hook (`additionalContext`) | Stop + PostToolUse hooks | same scripts; + MCP for in-session tool calls |
+| OpenCode | AGENTS.md → agent calls `recall` (MCP) | plugin `session.idle`/`session.compacted` | no inject-capable hook, so prompt-driven recall |
+
+## Roadmap
+
+- **Phase 1 ✓** — Claude Code: file store, grep recall, distillation, anti-rot.
+- **Phase 2 ✓** — Codex + OpenCode on the same store via a stdlib MCP server + installers.
+- **Phase 3** — embeddings + open vector DB only if scale outgrows grep; document ingest via OCR.
+
+## Credits
+
+foldcrumbs adapts a few utilities from [memanto](https://github.com/moorcheh-ai/memanto)
+(MIT, © Moorcheh / Edge AI Innovations): the typed-memory categories and confidence/decay
+model, the session-distillation approach, the transcript-reading helper, and the context-block
+rendering idea. These are reimplemented here against a file store; the Moorcheh retrieval engine
+is not used. Full notice in [LICENSE](LICENSE). Thanks to the memanto authors for releasing it
+under MIT.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

foldcrumbs-0.3.0/foldcrumbs/__init__.py

@@ -0,0 +1,9 @@
+"""foldcrumbs — persistent cross-session memory for coding agents.
+
+File-based memory store + lifecycle hooks for Claude Code. No external
+service, no vector DB: retrieval is done by the agent's own grep over the
+memory folder, and a local OpenAI-compatible LLM is used only for async
+distillation. Pure stdlib, so hook scripts never fail on a missing import.
+"""
+
+__version__ = "0.3.0"

foldcrumbs-0.3.0/foldcrumbs/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

foldcrumbs-0.3.0/foldcrumbs/audit.py

@@ -0,0 +1,117 @@
+"""Store integrity audit + pruning.
+
+Link integrity: the index links to real files on disk (``store.rebuild_index``
+is path-based), so a dead link — or an active memory the index doesn't link —
+just means the index is stale; ``heal_index`` rebuilds it. Pollution: a memory
+whose title/content is a structural tooling artifact (markdown table, code
+fence, status glyphs, the local-command caveat — distill's strict detector) is
+never durable knowledge and can be pruned. The strict detector deliberately
+excludes prose that merely mentions MEMORY.md so legitimate foldcrumbs design notes
+are never deleted. Superseded/deleted records keep their
+files but drop out of the index/recall; ``prune`` clears those too.
+"""
+
+from __future__ import annotations
+
+import re
+
+from . import config, store
+from .distill import _is_hard_artifact
+
+_LINK_RE = re.compile(r"\]\(([^)]+\.md)\)")
+# compute_confidence below this is low-trust (stale/contradicted); prune only on
+# explicit request, never automatically.
+STALE_CONF = 0.3
+
+
+def _name(m) -> str:
+    return m.source_path or m.filename()
+
+
+def _index_links(cwd=None) -> set[str]:
+    p = config.index_path(cwd)
+    if not p.exists():
+        return set()
+    try:
+        return set(_LINK_RE.findall(p.read_text(encoding="utf-8")))
+    except OSError:
+        return set()
+
+
+def audit(cwd=None) -> dict:
+    """Read-only report: dead index links, orphaned active memories (on disk but
+    unlinked), artifact pollution, and low-trust/stale memories."""
+    linked = _index_links(cwd)
+    mems = list(store.iter_memories(cwd))
+    active = [m for m in mems if m.status == "active"]
+    on_disk = {_name(m) for m in mems}
+    active_names = {_name(m) for m in active}
+    return {
+        "dead_links": sorted(t for t in linked if t not in on_disk),
+        "orphans": sorted(n for n in active_names if n not in linked),
+        "pollution": sorted(_name(m) for m in active
+                            if _is_hard_artifact(m.title) or _is_hard_artifact(m.content)),
+        "stale": sorted(_name(m) for m in active
+                        if m.compute_confidence() < STALE_CONF),
+        "active": len(active),
+        "total": len(mems),
+    }
+
+
+def heal_index(cwd=None) -> bool:
+    """Rebuild the index if it is stale (dead links or unlinked active memories).
+
+    Cheap and idempotent; returns True iff it rebuilt. Callers that share a store
+    across machines should gate this on ``config.distill_enabled()`` so only a
+    writing machine repairs (avoids sync churn)."""
+    a = audit(cwd)
+    if a["dead_links"] or a["orphans"]:
+        store.rebuild_index(cwd)
+        return True
+    return False
+
+
+def _delete(name: str, cwd=None) -> bool:
+    try:
+        (config.memory_dir(cwd) / name).unlink()
+        return True
+    except OSError:
+        return False
+
+
+def prune_artifacts(cwd=None) -> list[str]:
+    """Delete active memories whose text is a clear tooling artifact, then rebuild
+    the index. Conservative — only unambiguous artifacts. Returns deleted names."""
+    removed = [
+        _name(m)
+        for m in list(store.iter_memories(cwd))
+        if m.status == "active" and (_is_hard_artifact(m.title) or _is_hard_artifact(m.content))
+    ]
+    removed = [n for n in removed if _delete(n, cwd)]
+    if removed:
+        store.rebuild_index(cwd)
+    return removed
+
+
+def prune(cwd=None, apply: bool = False, include_stale: bool = False) -> dict:
+    """Find (and with ``apply``, delete) prune candidates.
+
+    Candidates: superseded/deleted records (files left behind), active artifact
+    pollution, and — only with ``include_stale`` — low-trust active memories.
+    Dry-run by default; rebuilds the index when it deletes anything."""
+    candidates: dict[str, str] = {}
+    for m in store.iter_memories(cwd):
+        name = _name(m)
+        if m.status in ("deleted", "superseded"):
+            candidates[name] = "superseded/deleted"
+        elif m.status == "active" and (_is_hard_artifact(m.title) or _is_hard_artifact(m.content)):
+            candidates[name] = "artifact"
+        elif (include_stale and m.status == "active"
+              and m.compute_confidence() < STALE_CONF):
+            candidates[name] = "stale"
+    removed: list[str] = []
+    if apply and candidates:
+        removed = [n for n in candidates if _delete(n, cwd)]
+        if removed:
+            store.rebuild_index(cwd)
+    return {"candidates": candidates, "removed": removed, "applied": apply}