wikimoth 0.1.0__tar.gz

wikimoth-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 Julian Geymonat
+
+   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.

wikimoth-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: wikimoth
+Version: 0.1.0
+Summary: Deterministic, token-minimal, reproducible memory for Claude and agents: wikilink-graph retrieval, then compaction, then a Claude reader.
+Author: Julian Geymonat
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/juliangeymonat-jpg/wikimoth
+Keywords: rag,memory,agents,claude,wikilinks,multi-hop,deterministic
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: hybrid
+Requires-Dist: rank_bm25; extra == "hybrid"
+Provides-Extra: dense
+Requires-Dist: transformers; extra == "dense"
+Requires-Dist: torch; extra == "dense"
+Requires-Dist: numpy; extra == "dense"
+Provides-Extra: claude
+Requires-Dist: anthropic; extra == "claude"
+Provides-Extra: tokens
+Requires-Dist: tiktoken; extra == "tokens"
+Provides-Extra: headroom
+Requires-Dist: headroom; extra == "headroom"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: rank_bm25; extra == "dev"
+Dynamic: license-file
+
+# WikiMoth
+
+### Connects the dots. The same way, every time.
+
+**Deterministic, token-minimal, auditable memory for Claude and agents.** Point WikiMoth at a
+folder of `[[wikilink]]` notes (an Obsidian vault, or Claude's own memory folder) and it
+follows the authored links to the answer flat search can't reach, shows you the exact note-chain
+behind it, and feeds the reader ~99% fewer tokens than pasting the whole vault. Pure markdown,
+no GPU, no vector DB, no LLM in the retrieval loop.
+
+```bash
+pip install wikimoth
+wikimoth install      # capture: turn your Claude Code sessions into a [[wikilink]] vault
+wikimoth serve        # browse the vault + see "what memory fed this answer"
+```
+
+---
+
+## Why WikiMoth
+
+Most agent memory is either *paste the whole notes folder into context* (expensive, and the model
+gets lost in the middle) or *LLM-summarised similarity search* (lossy, and non-deterministic:
+the same question can return different memory next week). WikiMoth takes a different bet: your notes
+**are** the store (plain markdown), the graph is **authored** (your `[[wikilinks]]`, no embeddings
+to train or drift), and retrieval is **code, not a model**, so it's reproducible and you can read
+exactly why each note was chosen.
+
+|  | **WikiMoth** | BM25 | Vector RAG | claude-mem | LLM Wiki (Karpathy) |
+|---|:--:|:--:|:--:|:--:|:--:|
+| Connects the dots (multi-hop over authored `[[links]]`) | ✅ | ❌ | ❌ | ❌ | ✅ *(agentic)* |
+| Deterministic retrieval (same query → same result) | ✅ | ✅ | ✅ | ❌ | ❌ |
+| No LLM call to retrieve | ✅ | ✅ | ✅ | ~ | ❌ |
+| Auditable note-chain (which notes produced the answer) | ✅ | ~ | ❌ | ❌ | ~ |
+| Direct-lookup recall@8 (real vault) | 1.00 | 1.00 | 1.00 | ~ | ~ |
+| No GPU / no vector DB / no index build | ✅ | ✅ | ❌ | ~ | ✅ |
+| Plain-markdown store (open in any editor) | ✅ | ~ | ❌ | ❌ | ✅ |
+| Token-minimal vs dumping the vault | ✅ −99% | ✅ −99% | ✅ −99% | ✅ | ~ |
+| Deterministic, API-free auto-capture | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+<sub>LLM Wiki *follows* links and skips the vector DB like WikiMoth, but an **LLM writes and reads** the wiki, so retrieval is agentic (an LLM call per recall, not reproducible), while its curated pages are richer. `~` = partial / not independently benchmarked.</sub>
+
+The edge is the **combination**, not higher recall: WikiMoth *matches* flat search on the basics and
+adds connect-the-dots + determinism + an audit trail + a plain-markdown store. See
+[Honest limits](#honest-limits) for exactly where it ties and where it wins.
+
+### Compared to Karpathy's LLM Wiki
+
+WikiMoth shares the substrate Andrej Karpathy's *LLM Wiki* pattern popularised: plain-markdown
+`[[wikilink]]` notes, no vector DB, but flips the **engine**. In the LLM-Wiki pattern an **LLM
+writes *and* reads** the wiki: rich, source-cited pages, but recall is *agentic* (it costs an LLM
+call and the path isn't reproducible). WikiMoth computes the edges in **code** and retrieves with a
+**fixed algorithm, no LLM in the loop** → the same note-chain every time, reproducible and
+auditable. They're complementary, not competing: point WikiMoth at a Karpathy-style wiki and you get
+deterministic multi-hop retrieval over it. (We don't claim to be "better" than the LLM Wiki: it
+curates richer pages; we retrieve deterministically.)
+
+## Quickstart (read)
+
+```python
+from wikimoth import MemoryRAG, EchoReader
+
+rag = MemoryRAG(reader=EchoReader())          # API-free default reader
+rag.index("path/to/your/wikilink/vault")      # notes → ~400-token chunks, graph built
+
+chunks, tokens = rag.retrieve("a connect-the-dots question?", top_k=8)
+print(f"{len(chunks)} chunks, {tokens} tokens to feed the reader")
+
+print(rag.answer("a connect-the-dots question?"))   # retrieve → compact → read
+```
+
+Swap in a real Claude answer (only touches the API when constructed):
+
+```python
+from wikimoth import MemoryRAG, ClaudeReader
+rag = MemoryRAG(reader=ClaudeReader(model="claude-sonnet-4-6"))   # needs ANTHROPIC_API_KEY
+```
+
+## See what memory fed an answer: `wikimoth serve`
+
+```bash
+wikimoth serve                 # serves http://127.0.0.1:8765 (local-only)
+wikimoth serve --vault PATH --port 8080
+```
+
+A zero-dependency local web viewer (pure stdlib, no Flask, no JS framework, no network):
+
+- **browse + search** your notes,
+- the authored **`[[wikilink]]` graph** (the same edges the retriever walks),
+- and the one that matters, **"what memory fed this answer"**: type a question and see the exact
+  note-chain WikiMoth would feed a reader, with per-chunk hop distance, token counts, and the `−N%`
+  vs dumping the whole vault. Retrieval only: no LLM call, no API key, deterministic.
+
+Because the store is plain markdown, you can equally open the same vault in Obsidian or VS Code;
+the viewer is a convenience, not a lock-in.
+
+## Capture: sessions → notes (the write half)
+
+Retrieval needs a `[[wikilink]]` vault; hand-authoring one is the friction. `wikimoth.capture` builds
+it automatically by installing Claude Code lifecycle hooks that turn each session into **one**
+deterministic markdown note.
+
+**The invariant that matters:** a note's `[[wikilinks]]` (the graph edges) are computed by code
+(string/path matching), **never by a model**. An LLM may *optionally* draft the summary prose
+(`WIKIMOTH_LLM_PROSE=1`), but any `[[...]]` it emits is stripped, never parsed as an edge. So the
+graph is reproducible (same session + vault → same edges) and auditable. Default capture is fully
+deterministic and makes **zero API calls**.
+
+```bash
+wikimoth install                 # writes 5 hooks into ./.claude/settings.json (absolute interpreter path)
+wikimoth install --user          # ~/.claude/settings.json instead
+wikimoth install --vault PATH    # choose where notes go (sets WIKIMOTH_VAULT)
+wikimoth status                  # vault, note/session/buffer counts, hook state
+wikimoth uninstall               # remove the hooks again
+```
+
+Lifecycle: **SessionStart** recalls recent sessions into context · **UserPromptSubmit / PostToolUse**
+buffer the session · **Stop / SessionEnd** write one note. The captured notes are exactly what the
+read pipeline indexes; capture and retrieval close the loop.
+
+## Install
+
+WikiMoth's core is **pure stdlib** (`dependencies = []`): the retrieval engine, chunker, wikilink
+graph, pipeline and capture are all vendored under `wikimoth/`: nothing extra to install, no GPU, no
+vector DB.
+
+```bash
+pip install wikimoth
+# before the PyPI release, install from source:
+pip install "git+https://github.com/juliangeymonat-jpg/wikimoth"
+# optional extras:
+pip install "wikimoth[hybrid]"          # BM25-seeded HybridRetriever (best direct-lookup + multi-hop)
+pip install "wikimoth[claude,tokens]"   # real Claude reader + exact tiktoken counts
+```
+
+Extras: `hybrid` = BM25-seeded retriever (`rank_bm25`) · `claude` = the `anthropic` reader ·
+`tokens` = exact token counts (`tiktoken`) · `dense` = the dense benchmark baseline · `headroom` =
+reversible CCR compaction.
+
+## How it works
+
+**retrieve → compact → read.** `index()` splits each note into ~400-token chunks (~50 overlap),
+keeping per-chunk note identity so the `[[wikilink]]` graph still connects across chunks (multi-hop
+at chunk granularity). `GraphRetriever(source="wikilinks")` seeds lexically, then walks the authored
+links, so a passage *not* lexically similar to the question but *reachable by a link* still gets
+pulled. An optional compaction stage (reversible CCR via
+[`chopratejas/headroom`](https://github.com/chopratejas/headroom)) shrinks passages further before
+the (paid) reader; it degrades to a no-op if headroom isn't installed.
+
+A pure-navigation hub (a table-of-contents like `MEMORY.md`) can be indexed as **graph edges only**
+(`exclude_content`, default `("MEMORY.md",)`): its `[[links]]` build edges and it stays a BFS
+waypoint, but its own chunks never reach the reader.
+
+Every stage is constructor-injectable via `MemoryRAG(retriever=…, compactor=…, reader=…)`, so you can
+swap the retriever (e.g. the BM25-seeded `HybridRetriever`), the compactor, or the reader.
+
+## Benchmark: tokens fed to the reader
+
+`wikimoth.benchmark.harness` measures *tokens fed to the reader* (what you actually pay for) across
+arms over the **same** vault and questions:
+
+| arm | feeds the reader | status |
+|---|---|---|
+| `dump` | the whole vault | baseline |
+| `deterministic` | wikilink-graph retrieval | implemented |
+| `deterministic_compacted` | retrieval + Headroom | implemented |
+| `agentic` | an LLM iteratively browses & picks | stub (needs LLM tool-calls) |
+
+No paid API calls run by default; every arm's reader defaults to the API-free `EchoReader`.
+
+## Honest limits
+
+WikiMoth's value is **deterministic, auditable, token-minimal, plain-markdown** memory with a real
+multi-hop capability, not "better retrieval than BM25". Specifically:
+
+- **The −99% is vs *dumping the vault*** (≈5k vs ~482k tokens on a real 356-note vault), not vs
+  BM25: a tuned BM25-RAG also feeds ~5k. The win is against the realistic status quo (paste
+  everything / naive whole-note RAG), and it's deterministic.
+- **On a typical real vault, retrieval ≈ BM25.** Direct-lookup recall@8 ties at 1.00. The
+  multi-hop / connect-the-dots win (0% → up to 100% where flat search scores zero) shows up on
+  **curated, link-heavy** corpora; on an average vault, hybrid is *never worse than BM25*, not
+  strictly better on recall.
+- **Determinism** is inherent to any static retriever (BM25/dense too); WikiMoth's determinism win is
+  specifically **vs LLM-summarised memory** (which varies run to run).
+- The `agentic` benchmark arm and a published large-scale capture dogfood are not done yet.
+
+## Pluggable + License
+
+`MemoryRAG(retriever=…, compactor=…, reader=…)`; defaults `GraphRetriever(source="wikilinks")` /
+`NoOpCompactor` / `EchoReader`. Anything satisfying the small Protocols drops in.
+
+Apache-2.0; see [LICENSE](LICENSE). © 2026 Julian Geymonat.

wikimoth-0.1.0/README.md

@@ -0,0 +1,191 @@
+# WikiMoth
+
+### Connects the dots. The same way, every time.
+
+**Deterministic, token-minimal, auditable memory for Claude and agents.** Point WikiMoth at a
+folder of `[[wikilink]]` notes (an Obsidian vault, or Claude's own memory folder) and it
+follows the authored links to the answer flat search can't reach, shows you the exact note-chain
+behind it, and feeds the reader ~99% fewer tokens than pasting the whole vault. Pure markdown,
+no GPU, no vector DB, no LLM in the retrieval loop.
+
+```bash
+pip install wikimoth
+wikimoth install      # capture: turn your Claude Code sessions into a [[wikilink]] vault
+wikimoth serve        # browse the vault + see "what memory fed this answer"
+```
+
+---
+
+## Why WikiMoth
+
+Most agent memory is either *paste the whole notes folder into context* (expensive, and the model
+gets lost in the middle) or *LLM-summarised similarity search* (lossy, and non-deterministic:
+the same question can return different memory next week). WikiMoth takes a different bet: your notes
+**are** the store (plain markdown), the graph is **authored** (your `[[wikilinks]]`, no embeddings
+to train or drift), and retrieval is **code, not a model**, so it's reproducible and you can read
+exactly why each note was chosen.
+
+|  | **WikiMoth** | BM25 | Vector RAG | claude-mem | LLM Wiki (Karpathy) |
+|---|:--:|:--:|:--:|:--:|:--:|
+| Connects the dots (multi-hop over authored `[[links]]`) | ✅ | ❌ | ❌ | ❌ | ✅ *(agentic)* |
+| Deterministic retrieval (same query → same result) | ✅ | ✅ | ✅ | ❌ | ❌ |
+| No LLM call to retrieve | ✅ | ✅ | ✅ | ~ | ❌ |
+| Auditable note-chain (which notes produced the answer) | ✅ | ~ | ❌ | ❌ | ~ |
+| Direct-lookup recall@8 (real vault) | 1.00 | 1.00 | 1.00 | ~ | ~ |
+| No GPU / no vector DB / no index build | ✅ | ✅ | ❌ | ~ | ✅ |
+| Plain-markdown store (open in any editor) | ✅ | ~ | ❌ | ❌ | ✅ |
+| Token-minimal vs dumping the vault | ✅ −99% | ✅ −99% | ✅ −99% | ✅ | ~ |
+| Deterministic, API-free auto-capture | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+<sub>LLM Wiki *follows* links and skips the vector DB like WikiMoth, but an **LLM writes and reads** the wiki, so retrieval is agentic (an LLM call per recall, not reproducible), while its curated pages are richer. `~` = partial / not independently benchmarked.</sub>
+
+The edge is the **combination**, not higher recall: WikiMoth *matches* flat search on the basics and
+adds connect-the-dots + determinism + an audit trail + a plain-markdown store. See
+[Honest limits](#honest-limits) for exactly where it ties and where it wins.
+
+### Compared to Karpathy's LLM Wiki
+
+WikiMoth shares the substrate Andrej Karpathy's *LLM Wiki* pattern popularised: plain-markdown
+`[[wikilink]]` notes, no vector DB, but flips the **engine**. In the LLM-Wiki pattern an **LLM
+writes *and* reads** the wiki: rich, source-cited pages, but recall is *agentic* (it costs an LLM
+call and the path isn't reproducible). WikiMoth computes the edges in **code** and retrieves with a
+**fixed algorithm, no LLM in the loop** → the same note-chain every time, reproducible and
+auditable. They're complementary, not competing: point WikiMoth at a Karpathy-style wiki and you get
+deterministic multi-hop retrieval over it. (We don't claim to be "better" than the LLM Wiki: it
+curates richer pages; we retrieve deterministically.)
+
+## Quickstart (read)
+
+```python
+from wikimoth import MemoryRAG, EchoReader
+
+rag = MemoryRAG(reader=EchoReader())          # API-free default reader
+rag.index("path/to/your/wikilink/vault")      # notes → ~400-token chunks, graph built
+
+chunks, tokens = rag.retrieve("a connect-the-dots question?", top_k=8)
+print(f"{len(chunks)} chunks, {tokens} tokens to feed the reader")
+
+print(rag.answer("a connect-the-dots question?"))   # retrieve → compact → read
+```
+
+Swap in a real Claude answer (only touches the API when constructed):
+
+```python
+from wikimoth import MemoryRAG, ClaudeReader
+rag = MemoryRAG(reader=ClaudeReader(model="claude-sonnet-4-6"))   # needs ANTHROPIC_API_KEY
+```
+
+## See what memory fed an answer: `wikimoth serve`
+
+```bash
+wikimoth serve                 # serves http://127.0.0.1:8765 (local-only)
+wikimoth serve --vault PATH --port 8080
+```
+
+A zero-dependency local web viewer (pure stdlib, no Flask, no JS framework, no network):
+
+- **browse + search** your notes,
+- the authored **`[[wikilink]]` graph** (the same edges the retriever walks),
+- and the one that matters, **"what memory fed this answer"**: type a question and see the exact
+  note-chain WikiMoth would feed a reader, with per-chunk hop distance, token counts, and the `−N%`
+  vs dumping the whole vault. Retrieval only: no LLM call, no API key, deterministic.
+
+Because the store is plain markdown, you can equally open the same vault in Obsidian or VS Code;
+the viewer is a convenience, not a lock-in.
+
+## Capture: sessions → notes (the write half)
+
+Retrieval needs a `[[wikilink]]` vault; hand-authoring one is the friction. `wikimoth.capture` builds
+it automatically by installing Claude Code lifecycle hooks that turn each session into **one**
+deterministic markdown note.
+
+**The invariant that matters:** a note's `[[wikilinks]]` (the graph edges) are computed by code
+(string/path matching), **never by a model**. An LLM may *optionally* draft the summary prose
+(`WIKIMOTH_LLM_PROSE=1`), but any `[[...]]` it emits is stripped, never parsed as an edge. So the
+graph is reproducible (same session + vault → same edges) and auditable. Default capture is fully
+deterministic and makes **zero API calls**.
+
+```bash
+wikimoth install                 # writes 5 hooks into ./.claude/settings.json (absolute interpreter path)
+wikimoth install --user          # ~/.claude/settings.json instead
+wikimoth install --vault PATH    # choose where notes go (sets WIKIMOTH_VAULT)
+wikimoth status                  # vault, note/session/buffer counts, hook state
+wikimoth uninstall               # remove the hooks again
+```
+
+Lifecycle: **SessionStart** recalls recent sessions into context · **UserPromptSubmit / PostToolUse**
+buffer the session · **Stop / SessionEnd** write one note. The captured notes are exactly what the
+read pipeline indexes; capture and retrieval close the loop.
+
+## Install
+
+WikiMoth's core is **pure stdlib** (`dependencies = []`): the retrieval engine, chunker, wikilink
+graph, pipeline and capture are all vendored under `wikimoth/`: nothing extra to install, no GPU, no
+vector DB.
+
+```bash
+pip install wikimoth
+# before the PyPI release, install from source:
+pip install "git+https://github.com/juliangeymonat-jpg/wikimoth"
+# optional extras:
+pip install "wikimoth[hybrid]"          # BM25-seeded HybridRetriever (best direct-lookup + multi-hop)
+pip install "wikimoth[claude,tokens]"   # real Claude reader + exact tiktoken counts
+```
+
+Extras: `hybrid` = BM25-seeded retriever (`rank_bm25`) · `claude` = the `anthropic` reader ·
+`tokens` = exact token counts (`tiktoken`) · `dense` = the dense benchmark baseline · `headroom` =
+reversible CCR compaction.
+
+## How it works
+
+**retrieve → compact → read.** `index()` splits each note into ~400-token chunks (~50 overlap),
+keeping per-chunk note identity so the `[[wikilink]]` graph still connects across chunks (multi-hop
+at chunk granularity). `GraphRetriever(source="wikilinks")` seeds lexically, then walks the authored
+links, so a passage *not* lexically similar to the question but *reachable by a link* still gets
+pulled. An optional compaction stage (reversible CCR via
+[`chopratejas/headroom`](https://github.com/chopratejas/headroom)) shrinks passages further before
+the (paid) reader; it degrades to a no-op if headroom isn't installed.
+
+A pure-navigation hub (a table-of-contents like `MEMORY.md`) can be indexed as **graph edges only**
+(`exclude_content`, default `("MEMORY.md",)`): its `[[links]]` build edges and it stays a BFS
+waypoint, but its own chunks never reach the reader.
+
+Every stage is constructor-injectable via `MemoryRAG(retriever=…, compactor=…, reader=…)`, so you can
+swap the retriever (e.g. the BM25-seeded `HybridRetriever`), the compactor, or the reader.
+
+## Benchmark: tokens fed to the reader
+
+`wikimoth.benchmark.harness` measures *tokens fed to the reader* (what you actually pay for) across
+arms over the **same** vault and questions:
+
+| arm | feeds the reader | status |
+|---|---|---|
+| `dump` | the whole vault | baseline |
+| `deterministic` | wikilink-graph retrieval | implemented |
+| `deterministic_compacted` | retrieval + Headroom | implemented |
+| `agentic` | an LLM iteratively browses & picks | stub (needs LLM tool-calls) |
+
+No paid API calls run by default; every arm's reader defaults to the API-free `EchoReader`.
+
+## Honest limits
+
+WikiMoth's value is **deterministic, auditable, token-minimal, plain-markdown** memory with a real
+multi-hop capability, not "better retrieval than BM25". Specifically:
+
+- **The −99% is vs *dumping the vault*** (≈5k vs ~482k tokens on a real 356-note vault), not vs
+  BM25: a tuned BM25-RAG also feeds ~5k. The win is against the realistic status quo (paste
+  everything / naive whole-note RAG), and it's deterministic.
+- **On a typical real vault, retrieval ≈ BM25.** Direct-lookup recall@8 ties at 1.00. The
+  multi-hop / connect-the-dots win (0% → up to 100% where flat search scores zero) shows up on
+  **curated, link-heavy** corpora; on an average vault, hybrid is *never worse than BM25*, not
+  strictly better on recall.
+- **Determinism** is inherent to any static retriever (BM25/dense too); WikiMoth's determinism win is
+  specifically **vs LLM-summarised memory** (which varies run to run).
+- The `agentic` benchmark arm and a published large-scale capture dogfood are not done yet.
+
+## Pluggable + License
+
+`MemoryRAG(retriever=…, compactor=…, reader=…)`; defaults `GraphRetriever(source="wikilinks")` /
+`NoOpCompactor` / `EchoReader`. Anything satisfying the small Protocols drops in.
+
+Apache-2.0; see [LICENSE](LICENSE). © 2026 Julian Geymonat.

wikimoth-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wikimoth"
+version = "0.1.0"
+description = "Deterministic, token-minimal, reproducible memory for Claude and agents: wikilink-graph retrieval, then compaction, then a Claude reader."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Julian Geymonat" }]
+keywords = ["rag", "memory", "agents", "claude", "wikilinks", "multi-hop", "deterministic"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Core WikiMoth is PURE STDLIB — retrieval (GraphRetriever), chunking, the
+# wikilink graph, the pipeline and capture are all vendored in wikimoth/retrieval/
+# (Julian's own Apache-2.0 code). No hard runtime dependency; everything below
+# is opt-in via extras and import-guarded.
+dependencies = []
+
+[project.optional-dependencies]
+# BM25-seeded HybridRetriever (the v2 default for best direct-lookup + multi-hop).
+hybrid = ["rank_bm25"]
+# Dense (semantic) baseline used in the benchmark comparison.
+dense = ["transformers", "torch", "numpy"]
+# Real Claude reader (otherwise EchoReader, the API-free default, is used).
+claude = ["anthropic"]
+# Most representative token counting (else a len//4 estimate is used).
+tokens = ["tiktoken"]
+# Reversible CCR compaction (chopratejas/headroom, Apache-2.0); import-guarded.
+headroom = ["headroom"]
+dev = ["pytest>=7", "rank_bm25"]
+
+[project.scripts]
+# `wikimoth install` wires the capture hooks into Claude Code's settings.json
+# (the pip-native equivalent of `npx <tool> install`).
+wikimoth = "wikimoth.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/juliangeymonat-jpg/wikimoth"
+
+[tool.setuptools.packages.find]
+include = ["wikimoth*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wikimoth-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+