memcrumbs 0.2.0__tar.gz

memcrumbs-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

memcrumbs-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: memcrumbs
+Version: 0.2.0
+Summary: Breadcrumbs of project memory for coding agents: a markdown wiki + token-efficient index (stdlib only)
+License-Expression: Apache-2.0
+Keywords: agents,claude-code,wiki,memory,search,sqlite,fts5
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# memcrumbs
+
+**Project memory for Claude Code and other coding agents: a small markdown wiki your agent reads before it
+reads your code, and a local index that answers in a few hundred tokens.**
+
+Every new session, a coding agent starts from zero. It greps, it reads whole files, it rediscovers the same
+facts, and it repeats mistakes your team already made. Notes kept by hand drift until they contradict the
+system, and sometimes they leak a secret.
+
+memcrumbs gives each project a memory that stays small, current and safe.
+
+## What it does for you
+
+- **Your agent starts every session knowing the rules.** A short header (under 1,000 tokens) brings your
+  standing rules, the project map, the top gotchas and recent journal lines, so "never deploy on Friday" is
+  read before anything else.
+- **Answers instead of file dumps.** `memcrumbs find "how do I roll back a bad deploy"` returns a few ranked hits
+  with `path:line`, how old each one is and whether it is still current. The agent then opens one section or
+  one function, not a 4,000-line file.
+- **It remembers what happened and why.** Decisions (including the ones you rejected), incidents with the
+  symptom someone will see next time, runbooks, and a dated journal. Asking "did we ever try Postgres?" finds
+  the rejected decision instead of a fresh attempt.
+- **It knows when it may be wrong.** Every hit says how long ago it was verified, flags `STALE` pages, and says
+  `SRC-CHANGED` when the code a page describes changed after the page was checked.
+- **It tells the agent what the wiki says about a file before it edits it.** `memcrumbs about deploy.ps1` lists
+  the decisions, incidents and gotchas that mention it.
+- **It keeps one current value per fact.** Versions, ports and hosts live in one table, optionally read straight
+  from the source file, and `check` flags pages that still state an old value.
+- **It notices things for you, and asks first.** `memcrumbs suggest` offers near-duplicate pages to merge,
+  questions the wiki could not answer, gotchas that can become permission prompts, repeated command sequences
+  that could become a skill, and auto-memory notes the wiki already holds. Nothing changes until you say yes,
+  and every change can be undone byte for byte.
+- **Your secrets stay out.** Everything indexed, printed or written is redacted; `.env` files and keys are never
+  indexed; `memcrumbs scan` checks a folder or a package before you publish it.
+- **You stay in control of token spend.** Re-indexing is free and local. Rewriting stale pages is agent work, so
+  `memcrumbs plan` and the dashboard let you pick the pages and the budget.
+
+Standard library only: no model calls, no network, no background service, no per-tool-call hooks. Your wiki is
+plain markdown in your own folder.
+
+## What it looks like
+
+```text
+$ memcrumbs find "how do I roll back a bad deploy" -n 3
+[run ] Roll back booking app — wiki/runbooks/rollback-booking.md:1 · v8d
+       …booking [release] in under two minutes by repointing the current junction [Roll back] booking…
+[run ] Deploy booking app — wiki/runbooks/deploy-booking.md:1 · v8d
+       Numbered steps to [ship] a new booking app [release] to web-srv, with the…
+[wiki] Booking web app › Behaviour notes — wiki/components/booking-app.md:23 · v8d
+       …[Deploy] with [[deploy-booking]]; [undo] with [[rollback-booking]].
+read: memcrumbs page rollback-booking · more: -n 6
+
+$ memcrumbs about repo/ops/EmberOps.psm1
+EmberOps.psm1 — cited by 1 decision (ACCEPTED), 2 incidents, 1 runbook
+[dec ] Unlimited execution time for daemon tasks — wiki/decisions/2026-08-12-execution-time-limit-zero.md:1 · ACCEPTED
+[inc ] BOM in a PowerShell script silently broke a scheduled task — wiki/incidents/2026-07-29-bom-breaks-scheduled-task.md:1
+…
+```
+
+(From the invented sample project in `bench/kiln`.)
+
+## Install
+
+```bash
+pip install git+https://github.com/mikedconcepcion/memcrumbs   # Python 3.11+; puts `memcrumbs` on PATH
+```
+
+Your wikis live outside the package, in `~/.memcrumbs/projects` by default. To keep them somewhere else (for
+example a private git repo), set `projects_dir` in `~/.memcrumbs/config.toml` or the `MEMCRUMBS_PROJECTS`
+environment variable.
+
+## Quick start
+
+```bash
+memcrumbs init myapp --repo /code/myapp --title "My App"   # creates the project and a starter wiki
+memcrumbs -p myapp index                                   # builds the index (seconds; incremental afterwards)
+memcrumbs -p myapp wire --repo /code/myapp --apply --allow # CLAUDE.md block, session header hook, skill
+memcrumbs -p myapp doctor                                  # checks the install, the index and the hook
+```
+
+From then on, every Claude Code session in that repo starts with the header, and the agent looks things up with
+`memcrumbs find`. Inside the repo (or the project folder) `-p` can be left out. Write the wiki as you go:
+
+```bash
+memcrumbs log "rotated the API key" --tag ops                        # a dated journal line
+memcrumbs decision "Move bookings to Postgres" --status rejected --why "too much to run for our size"
+memcrumbs incident "Nightly task died after 72 h" --symptom "no reports since Tuesday" --cause "task time limit"
+memcrumbs check                                                      # lint: secrets, links, stale pages, …
+```
+
+`wire --remove --apply` takes everything out again, byte for byte. A step-by-step setup that your agent can
+follow is in [docs/adopting.md](docs/adopting.md).
+
+## Everyday commands
+
+| Command | What you get |
+|---|---|
+| `find <words>` | Ranked hits with `path:line`, age and status. Filters: `kind:decision status:rejected path:booking` |
+| `page <name> [section]` | A page, or one section of it |
+| `outline <file>` · `sym <name> [--body]` | Functions and classes with line ranges · where a symbol is defined |
+| `about <file>` · `fact [key]` | What the wiki says about a file · a current value with its source |
+| `log` · `decision` · `incident` · `rule` | Write the journal, a decision, an incident, a standing rule |
+| `verify <page>` · `supersede <page> --by <new>` | Mark a page re-checked today · replaced by a newer one |
+| `suggest` · `suggest apply ID` · `suggest undo ID` | Offers to improve the wiki and the agent setup, applied only on your yes |
+| `check` · `scan [path]` | Lint the wiki · secret-scan a folder, an sdist or a wheel |
+| `plan` · `dashboard --open` | What needs a refresh and what it would cost · an HTML overview |
+| `doctor` · `stats --usage` · `bench` | Health check · output size per command · lookup quality on your own questions |
+
+Every command takes `--json`. Full reference: [docs/cli.md](docs/cli.md).
+
+## Documentation
+
+- [Setting up a project](docs/adopting.md), step by step
+- [Writing good crumbs](docs/writing-crumbs.md): pages, rules, gotchas, decisions, incidents, facts
+- [Configuration](docs/config.md) · [Command reference](docs/cli.md)
+- [Plugins and packs](docs/plugins.md): add a source, a check, a header section or a language
+- [Security](SECURITY.md): what redaction promises and what it does not
+
+## Contributing and reporting bugs
+
+- **Found a bug?** [Open an issue](https://github.com/mikedconcepcion/memcrumbs/issues/new/choose) with the bug
+  template. Paste the output of `memcrumbs doctor --share`: it holds versions, counts and timings only, never
+  your paths, page text or secrets.
+- **An idea or a missing feature?** Use the feature request template. Say what you were trying to do.
+- **A security problem?** Please report it privately, as described in [SECURITY.md](SECURITY.md), not in a
+  public issue.
+- **Want to contribute code or docs?** See [CONTRIBUTING.md](CONTRIBUTING.md): how to run the tests, the few
+  rules the code follows, and what a good pull request looks like.
+
+## Status
+
+Alpha: usable day to day, with the command line and config still allowed to change before 1.0. Changes are
+listed in [CHANGELOG.md](CHANGELOG.md). License: [Apache-2.0](LICENSE).

memcrumbs-0.2.0/README.md

@@ -0,0 +1,133 @@
+# memcrumbs
+
+**Project memory for Claude Code and other coding agents: a small markdown wiki your agent reads before it
+reads your code, and a local index that answers in a few hundred tokens.**
+
+Every new session, a coding agent starts from zero. It greps, it reads whole files, it rediscovers the same
+facts, and it repeats mistakes your team already made. Notes kept by hand drift until they contradict the
+system, and sometimes they leak a secret.
+
+memcrumbs gives each project a memory that stays small, current and safe.
+
+## What it does for you
+
+- **Your agent starts every session knowing the rules.** A short header (under 1,000 tokens) brings your
+  standing rules, the project map, the top gotchas and recent journal lines, so "never deploy on Friday" is
+  read before anything else.
+- **Answers instead of file dumps.** `memcrumbs find "how do I roll back a bad deploy"` returns a few ranked hits
+  with `path:line`, how old each one is and whether it is still current. The agent then opens one section or
+  one function, not a 4,000-line file.
+- **It remembers what happened and why.** Decisions (including the ones you rejected), incidents with the
+  symptom someone will see next time, runbooks, and a dated journal. Asking "did we ever try Postgres?" finds
+  the rejected decision instead of a fresh attempt.
+- **It knows when it may be wrong.** Every hit says how long ago it was verified, flags `STALE` pages, and says
+  `SRC-CHANGED` when the code a page describes changed after the page was checked.
+- **It tells the agent what the wiki says about a file before it edits it.** `memcrumbs about deploy.ps1` lists
+  the decisions, incidents and gotchas that mention it.
+- **It keeps one current value per fact.** Versions, ports and hosts live in one table, optionally read straight
+  from the source file, and `check` flags pages that still state an old value.
+- **It notices things for you, and asks first.** `memcrumbs suggest` offers near-duplicate pages to merge,
+  questions the wiki could not answer, gotchas that can become permission prompts, repeated command sequences
+  that could become a skill, and auto-memory notes the wiki already holds. Nothing changes until you say yes,
+  and every change can be undone byte for byte.
+- **Your secrets stay out.** Everything indexed, printed or written is redacted; `.env` files and keys are never
+  indexed; `memcrumbs scan` checks a folder or a package before you publish it.
+- **You stay in control of token spend.** Re-indexing is free and local. Rewriting stale pages is agent work, so
+  `memcrumbs plan` and the dashboard let you pick the pages and the budget.
+
+Standard library only: no model calls, no network, no background service, no per-tool-call hooks. Your wiki is
+plain markdown in your own folder.
+
+## What it looks like
+
+```text
+$ memcrumbs find "how do I roll back a bad deploy" -n 3
+[run ] Roll back booking app — wiki/runbooks/rollback-booking.md:1 · v8d
+       …booking [release] in under two minutes by repointing the current junction [Roll back] booking…
+[run ] Deploy booking app — wiki/runbooks/deploy-booking.md:1 · v8d
+       Numbered steps to [ship] a new booking app [release] to web-srv, with the…
+[wiki] Booking web app › Behaviour notes — wiki/components/booking-app.md:23 · v8d
+       …[Deploy] with [[deploy-booking]]; [undo] with [[rollback-booking]].
+read: memcrumbs page rollback-booking · more: -n 6
+
+$ memcrumbs about repo/ops/EmberOps.psm1
+EmberOps.psm1 — cited by 1 decision (ACCEPTED), 2 incidents, 1 runbook
+[dec ] Unlimited execution time for daemon tasks — wiki/decisions/2026-08-12-execution-time-limit-zero.md:1 · ACCEPTED
+[inc ] BOM in a PowerShell script silently broke a scheduled task — wiki/incidents/2026-07-29-bom-breaks-scheduled-task.md:1
+…
+```
+
+(From the invented sample project in `bench/kiln`.)
+
+## Install
+
+```bash
+pip install git+https://github.com/mikedconcepcion/memcrumbs   # Python 3.11+; puts `memcrumbs` on PATH
+```
+
+Your wikis live outside the package, in `~/.memcrumbs/projects` by default. To keep them somewhere else (for
+example a private git repo), set `projects_dir` in `~/.memcrumbs/config.toml` or the `MEMCRUMBS_PROJECTS`
+environment variable.
+
+## Quick start
+
+```bash
+memcrumbs init myapp --repo /code/myapp --title "My App"   # creates the project and a starter wiki
+memcrumbs -p myapp index                                   # builds the index (seconds; incremental afterwards)
+memcrumbs -p myapp wire --repo /code/myapp --apply --allow # CLAUDE.md block, session header hook, skill
+memcrumbs -p myapp doctor                                  # checks the install, the index and the hook
+```
+
+From then on, every Claude Code session in that repo starts with the header, and the agent looks things up with
+`memcrumbs find`. Inside the repo (or the project folder) `-p` can be left out. Write the wiki as you go:
+
+```bash
+memcrumbs log "rotated the API key" --tag ops                        # a dated journal line
+memcrumbs decision "Move bookings to Postgres" --status rejected --why "too much to run for our size"
+memcrumbs incident "Nightly task died after 72 h" --symptom "no reports since Tuesday" --cause "task time limit"
+memcrumbs check                                                      # lint: secrets, links, stale pages, …
+```
+
+`wire --remove --apply` takes everything out again, byte for byte. A step-by-step setup that your agent can
+follow is in [docs/adopting.md](docs/adopting.md).
+
+## Everyday commands
+
+| Command | What you get |
+|---|---|
+| `find <words>` | Ranked hits with `path:line`, age and status. Filters: `kind:decision status:rejected path:booking` |
+| `page <name> [section]` | A page, or one section of it |
+| `outline <file>` · `sym <name> [--body]` | Functions and classes with line ranges · where a symbol is defined |
+| `about <file>` · `fact [key]` | What the wiki says about a file · a current value with its source |
+| `log` · `decision` · `incident` · `rule` | Write the journal, a decision, an incident, a standing rule |
+| `verify <page>` · `supersede <page> --by <new>` | Mark a page re-checked today · replaced by a newer one |
+| `suggest` · `suggest apply ID` · `suggest undo ID` | Offers to improve the wiki and the agent setup, applied only on your yes |
+| `check` · `scan [path]` | Lint the wiki · secret-scan a folder, an sdist or a wheel |
+| `plan` · `dashboard --open` | What needs a refresh and what it would cost · an HTML overview |
+| `doctor` · `stats --usage` · `bench` | Health check · output size per command · lookup quality on your own questions |
+
+Every command takes `--json`. Full reference: [docs/cli.md](docs/cli.md).
+
+## Documentation
+
+- [Setting up a project](docs/adopting.md), step by step
+- [Writing good crumbs](docs/writing-crumbs.md): pages, rules, gotchas, decisions, incidents, facts
+- [Configuration](docs/config.md) · [Command reference](docs/cli.md)
+- [Plugins and packs](docs/plugins.md): add a source, a check, a header section or a language
+- [Security](SECURITY.md): what redaction promises and what it does not
+
+## Contributing and reporting bugs
+
+- **Found a bug?** [Open an issue](https://github.com/mikedconcepcion/memcrumbs/issues/new/choose) with the bug
+  template. Paste the output of `memcrumbs doctor --share`: it holds versions, counts and timings only, never
+  your paths, page text or secrets.
+- **An idea or a missing feature?** Use the feature request template. Say what you were trying to do.
+- **A security problem?** Please report it privately, as described in [SECURITY.md](SECURITY.md), not in a
+  public issue.
+- **Want to contribute code or docs?** See [CONTRIBUTING.md](CONTRIBUTING.md): how to run the tests, the few
+  rules the code follows, and what a good pull request looks like.
+
+## Status
+
+Alpha: usable day to day, with the command line and config still allowed to change before 1.0. Changes are
+listed in [CHANGELOG.md](CHANGELOG.md). License: [Apache-2.0](LICENSE).

memcrumbs-0.2.0/memcrumbs/__init__.py

@@ -0,0 +1,6 @@
+"""memcrumbs - breadcrumbs of project memory for coding agents: a wiki plus a token-efficient index.
+
+Layers: core (this package: wiki, index, outline, checks) -> packs (memcrumbs.packs.*: reusable domain add-ons)
+-> project (<projects_dir>/<name>/: memcrumbs.toml, wiki/, plugins/ tailored to one project).
+"""
+__version__ = "0.2.0"

memcrumbs-0.2.0/memcrumbs/__main__.py

@@ -0,0 +1,3 @@
+from memcrumbs.cli import main
+
+main()

memcrumbs-0.2.0/memcrumbs/bench.py

@@ -0,0 +1,138 @@
+"""`memcrumbs bench QUESTIONS.toml`: recall@1 / recall@3 / MRR, tokens per answer and latency, against any
+project (public or private) with no code changes.
+
+    [[q]]
+    id = "rb-01"
+    q = "how do I roll back a bad deploy?"
+    expect = ["wiki/runbooks/rollback.md"]      # path suffixes; any one in the top k counts
+    category = "runbook"                        # optional; results are also broken down by category
+
+A hit matches an expected path when its file path ends with it (`wiki/x.md`, `repo/app.py`); `path#Section`
+also requires the hit's section to contain that text. Tokens are the `find` output's chars/4 (estimate)."""
+import io
+import json
+import time
+import tomllib
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from memcrumbs import cmd_read, writeset
+from memcrumbs.output import Out, est_tokens
+from memcrumbs.util import posix
+
+
+def load(path):
+    with open(path, "rb") as f:
+        qs = tomllib.load(f).get("q", [])
+    for i, q in enumerate(qs):
+        if not q.get("q") or not q.get("expect"):
+            raise SystemExit("bench: question %d needs q and expect" % (i + 1))
+        q.setdefault("id", "q%d" % (i + 1))
+    return qs
+
+
+def _match(hit, expect):
+    path = "/" + posix(hit["path"]).lstrip("/")
+    for e in expect:
+        target, _, section = e.partition("#")
+        if path.lower().endswith("/" + target.strip("/").lower()) and \
+                (not section or section.lower() in (hit.get("section") or "").lower()):
+            return True
+    return False
+
+
+def run(project, store, questions, k=8):
+    rows = []
+    for q in questions:
+        t0 = time.perf_counter()
+        hits = store.search(q["q"], kinds=q.get("kinds"), limit=k)
+        ms = (time.perf_counter() - t0) * 1000
+        buf = io.StringIO()
+        with redirect_stdout(buf):                                 # the exact text an agent would read
+            out = Out("find", None, project.redact)
+            cmd_read.find(out, project, store, q["q"], q.get("kinds"), k, track=False)
+            out.close()
+        rank = next((i + 1 for i, h in enumerate(hits) if _match(h, q["expect"])), None)
+        followed = next((i + 1 for i, h in enumerate(hits) if _match(h, q["expect"]) or
+                         (h.get("see") and _match(h["see"], q["expect"]))), None)
+        rows.append(dict(id=q["id"], q=q["q"], category=q.get("category", ""), paraphrase=bool(q.get("paraphrase")),
+                         rank=rank, followed=followed, ms=round(ms, 1), tokens=est_tokens(len(buf.getvalue())),
+                         top3=[project.rel(h["path"]) for h in hits[:3]]))
+    return rows
+
+
+def _agg(rows):
+    n = len(rows) or 1
+    ms, toks = sorted(r["ms"] for r in rows), sorted(r["tokens"] for r in rows)
+    pct = (lambda xs, p: xs[min(len(xs) - 1, int(p * len(xs)))] if xs else 0)
+    return dict(n=len(rows), recall_at_1=round(sum(1 for r in rows if r["rank"] == 1) / n, 3),
+                recall_at_3=round(sum(1 for r in rows if r["rank"] and r["rank"] <= 3) / n, 3),
+                recall_at_3_with_pointers=round(sum(1 for r in rows if r.get("followed") and r["followed"] <= 3) / n, 3),
+                mrr=round(sum(1 / r["rank"] for r in rows if r["rank"]) / n, 3),
+                tokens_mean=round(sum(toks) / n), tokens_p95=pct(toks, 0.95),
+                ms_mean=round(sum(ms) / n, 1), ms_p95=pct(ms, 0.95))
+
+
+def default_path(project):
+    """The project's own bench, grown from real use with `memcrumbs bench --add` (kept with the wiki)."""
+    return project.wiki / "bench.toml"
+
+
+def add(out, project, question, expects, category=""):
+    """Record a question the wiki should answer, with the file(s) that do. Run it when a lookup missed."""
+    from memcrumbs.curate import exact_page
+    if not expects:
+        raise SystemExit("memcrumbs: --add needs --expect <page or file>")
+    targets = []
+    for e in expects:
+        try:
+            targets.append(project.rel(exact_page(project, e)))
+        except SystemExit:
+            p = Path(e).expanduser().resolve()
+            if not p.exists():
+                raise SystemExit("memcrumbs: no page or file %r" % e)
+            try:
+                targets.append(posix(p.relative_to(project.dir)))
+            except ValueError:
+                targets.append(posix(p))
+    path = default_path(project)
+    head = "" if path.exists() else ("# Questions this wiki must answer (memcrumbs bench). Added with "
+                                      "`memcrumbs bench --add`.\n")
+    n = len(load(path)) + 1 if path.exists() else 1
+    entry = '%s\n[[q]]\nid = "real-%03d"\nq = %s\nexpect = [%s]\n%s' % (
+        head, n, json.dumps(project.redact(question), ensure_ascii=False), ", ".join(json.dumps(t) for t in targets),
+        ("category = %s\n" % json.dumps(category)) if category else "")
+    writeset.append_text(project, path, entry)
+    out.set(path=project.rel(path), id="real-%03d" % n, expect=targets)
+    out("added real-%03d to %s (%d questions) — memcrumbs bench to measure" % (n, project.rel(path), n))
+
+
+def report(out, project, store, path, min_recall3=None, k=8):
+    path = path or default_path(project)
+    if not Path(path).exists():
+        raise SystemExit("memcrumbs: no questions at %s — record real ones with: memcrumbs bench --add \"<question>\" "
+                         "--expect <page>" % posix(path))
+    rows = run(project, store, load(path), k)
+    total = _agg(rows)
+    cats = {c: _agg([r for r in rows if r["category"] == c]) for c in sorted({r["category"] for r in rows if r["category"]})}
+    para = _agg([r for r in rows if r["paraphrase"]])
+    misses = [r for r in rows if not r["rank"] or r["rank"] > 3]
+    out.list_key = "questions"
+    out.set(project=project.name, questions_file=posix(path), total=total, by_category=cats, paraphrase=para,
+            questions=rows)
+    out.hint("memcrumbs bench %s --json --full" % posix(path))
+    out("bench %s · %d questions · recall@1 %.3f · recall@3 %.3f · MRR %.3f" % (
+        project.name, total["n"], total["recall_at_1"], total["recall_at_3"], total["mrr"]))
+    out("recall@3 counting '→ see' pointers under a hit: %.3f" % total["recall_at_3_with_pointers"])
+    out("tokens/answer mean %d p95 %d (est.) · search latency mean %.1f ms p95 %.1f ms" % (
+        total["tokens_mean"], total["tokens_p95"], total["ms_mean"], total["ms_p95"]))
+    if para["n"]:
+        out("paraphrased questions: %d · recall@3 %.3f" % (para["n"], para["recall_at_3"]))
+    for c, a in cats.items():
+        out("  %-12s n=%-3d r@1 %.2f  r@3 %.2f" % (c, a["n"], a["recall_at_1"], a["recall_at_3"]))
+    for r in misses:
+        out("miss %s (rank %s): %s → %s" % (r["id"], r["rank"] or "-", r["q"], ", ".join(r["top3"]) or "no hits"))
+    if min_recall3 is not None and total["recall_at_3"] < min_recall3:
+        out("FAIL: recall@3 %.3f < %.3f" % (total["recall_at_3"], min_recall3))
+        return 1
+    return 0