remcycle 0.3.0__tar.gz

remcycle-0.3.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.db
+.local/
+mod/.claude/

remcycle-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.3.0
+
+- **remcycle is on PyPI.** `uv tool install remcycle` installs the `dream` command, and `uv tool upgrade remcycle` brings the latest release.
+- **The mod follows releases.** It is installed from the tag of the latest release, so `claude plugin update remcycle@remcycle` brings a release and nothing in between.
+- **`dream --version`** says which version of the command is installed.
+
+### Upgrading from 0.2.0 or earlier
+
+The command you have follows the repository, not releases. Replace it once, and update the mod:
+
+```bash
+uv tool install --reinstall remcycle
+claude plugin update remcycle@remcycle
+```
+
+If Claude set remcycle up for you from a folder such as `~/remcycle`, the mod was installed from that folder as well. Move it to the repository on GitHub, after which the folder can be deleted:
+
+```bash
+claude plugin marketplace remove remcycle
+claude plugin marketplace add lianmatsuo/remcycle
+claude plugin install remcycle@remcycle
+```
+
+## 0.2.0
+
+- **The daily dream is on by default.** Once a day, the first session after 20 hours starts the dream in the background, with no scheduler to set up. The panel asks once how much history it should read, shows when it last ran and why it went wrong if it did, and turns it off. `dream daily` makes the same changes from the command line.
+- **Memory stays free while a dream reads.** The model reads the sessions before the dream takes its turn at changing memory, so closing a thread or ruling on a question during a run works, and a close that does collide says to try again.
+- **Lighter model calls.** The dream's calls to Claude Code no longer carry the descriptions of your MCP servers and skills. One measured call went from about 183,000 tokens of context to about 500.
+
+## 0.1.0
+
+The first public release.
+
+- **The archive.** `dream ingest`, `search`, `show` and `purge`. Every session's prose is kept word for word in one local file, with secrets redacted and the projects you exclude left out.
+- **The dream.** `dream run` reads new sessions through your own Claude Code, keeps what you said or agreed to together with the words it came from, and checks every change before accepting it. `dream review` goes over the memories you already had. `dream publish` writes to the memory Claude Code itself loads, and only when you ask.
+- **The mod.** It hands each new session what was learned and what was left unfinished, gives Claude the `recall`, `close_thread` and `settle_memory` tools, and adds the `/remcycle` panel.
+- **Setup by Claude.** One prompt to paste. Claude does the install and stops for a yes before anything that costs model usage or changes how Claude Code runs.

remcycle-0.3.0/LICENSE

@@ -0,0 +1,177 @@
+
+                                 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

remcycle-0.3.0/NOTICE

@@ -0,0 +1,2 @@
+remcycle
+Copyright 2026 Lian Matsuo

remcycle-0.3.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: remcycle
+Version: 0.3.0
+Summary: Garbage collection for Claude Code's memory: rereads your sessions every day, keeps what you decided, and questions stale notes
+Project-URL: Homepage, https://github.com/lianmatsuo/remcycle
+Project-URL: Changelog, https://github.com/lianmatsuo/remcycle/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/lianmatsuo/remcycle/issues
+Author: Lian Matsuo
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lianmatsuo/remcycle/main/docs/images/header.png" alt="remcycle. Garbage collection for Claude Code's memory. A mod that rereads your sessions every day, keeps what you decided, and questions the notes that have gone stale." width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/lianmatsuo/remcycle/actions/workflows/check.yml"><img src="https://github.com/lianmatsuo/remcycle/actions/workflows/check.yml/badge.svg" alt="Checks"></a>
+  <a href="https://github.com/lianmatsuo/remcycle/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-Apache--2.0-555" alt="Licence: Apache-2.0"></a>
+  <img src="https://img.shields.io/badge/Claude%20Code-2.1.287%20or%20later-555" alt="Needs Claude Code 2.1.287 or later">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lianmatsuo/remcycle/main/docs/images/session.webp" alt="A Claude Code session with the remcycle panel beside it. The panel shows two questions waiting for a ruling, nine memories and where they came from, what was learned lately, and what earlier sessions left open." width="100%">
+</p>
+
+<p align="center"><sub>The shop project in the pictures is made up.</sub></p>
+
+Claude Code starts every session fresh, and the notes it keeps about your projects pile up until the old ones are wrong. remcycle keeps everything you and Claude said, and once a day it reads the new sessions in the background, keeps what you actually decided, and questions the rest. The sessions after that start knowing it.
+
+- **Sessions that start informed.** Each new session is handed what you have said applies to all your work, what was learned about the project, and what earlier sessions left unfinished.
+- **Memory you can trust.** Every memory points at the words it came from. Something only Claude concluded is never loaded as if you had said it, and a note you already had is never replaced without asking you.
+- **A list that stays short.** Stale, repeated and contradictory notes are found and put to you, so what loads at the start of a session does not keep growing.
+- **Recall.** Claude can search everything that was said in past sessions, get a summary of any the dream has read, and read the exact words back when it needs them.
+- **Everything on your machine.** The archive is one local file. The only thing that leaves is what the dream sends to the model, through your own Claude Code.
+
+## Get started
+
+You need [Claude Code](https://claude.com/claude-code) 2.1.287 or later and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install remcycle
+claude plugin marketplace add lianmatsuo/remcycle
+claude plugin install remcycle@remcycle
+```
+
+The first line installs the `dream` command, and the other two install the mod. Then:
+
+1. **Say what it should never read.** A client's or an employer's projects go in [the settings file](https://github.com/lianmatsuo/remcycle/blob/main/docs/reference.md#settings) before anything else, because the dream starts reading by itself.
+2. **Build the archive.** `dream ingest` copies what was said in your past sessions into one local file. It sends nothing anywhere.
+3. **Open the panel.** Start a new session and type `/remcycle`. It asks once how much of your history the daily dream should read: only new sessions, the week before too, or everything.
+
+From then on the dream runs by itself. Once a day, the first session after 20 hours starts it in the background, and it reads the sessions that are new. This is the part that uses your Claude plan: one long session came to about $0.60 at API prices. `dream daily off`, or the switch in the panel, turns it off, and `dream run` runs it at any time. [The daily dream](https://github.com/lianmatsuo/remcycle/blob/main/docs/schedule.md) has its settings, and how to run it at a fixed time instead.
+
+### Or let Claude set it up
+
+Paste this into Claude Code:
+
+```text
+Set up remcycle for me. Clone https://github.com/lianmatsuo/remcycle into ~/remcycle, or run git pull there if it is already cloned. Then read docs/setup-with-claude.md in that folder and follow it step by step.
+```
+
+Claude installs the command, asks which projects to leave out, and builds the archive. It asks you before loading the mod in every session, which also starts the daily dream, and asks how much of your history that dream should read. You can say no to either and turn it on later.
+
+The folder is only read for its guide, and can be deleted afterwards. [Removing it](https://github.com/lianmatsuo/remcycle/blob/main/docs/reference.md#removing-it) says how to undo each part.
+
+## The panel
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lianmatsuo/remcycle/main/docs/images/panel.webp" alt="The remcycle panel in full screen. On the left, three tiles: two questions need you, nine memories, the index five per cent full. Under them a question about where deploys go, with buttons to take the suggestion, keep the memory, add it to the chat or skip. On the right, what was learned lately, what was left open and what was closed lately." width="100%">
+</p>
+
+Type `/remcycle` in any session.
+
+- **Needs you.** Memories a session or a review has put in question, one at a time, with what the memory says and why it is doubted. You take the suggestion, keep the memory, or add it to the chat to talk it through.
+- **Memories.** How many there are and where each came from: you said it, you agreed to it, or it was written before remcycle.
+- **Index used.** How full the list is that Claude Code loads at the start of a session. This is the number remcycle exists to keep low.
+- **Learned lately, Left open, Closed lately.** The newest of each, with the whole list a button away. A thread closes when the work is done, and you can reopen one.
+
+## How it works
+
+```mermaid
+flowchart LR
+    work(["You and<br/>Claude Code"])
+    archive[("Archive<br/>word for word")]
+    dream{{"The dream<br/>once a day"}}
+    memory["Memory<br/>short, sourced notes"]
+    work -- "saved" --> archive
+    archive -- "what is new" --> dream
+    dream -- "what you decided" --> memory
+    memory -- "next session" --> work
+    dream -. "asks if unsure" .-> work
+```
+
+[How it works](https://github.com/lianmatsuo/remcycle/blob/main/docs/how-it-works.md) explains each part in plain words, with pictures.
+
+## A mod, not a prompt
+
+A skill or an instructions file is text that Claude reads and may or may not act on. remcycle is a mod: code that runs inside Claude Code and changes what a session does.
+
+- **When a conversation starts**, it hands Claude what you have said and what earlier sessions left unfinished.
+- **It gives Claude three tools.** `recall` searches past sessions, `close_thread` marks unfinished work done, and `settle_memory` applies a ruling the two of you reached.
+- **It adds a panel.** `/remcycle` shows what it holds, and lets you rule on what it doubts.
+- **When a session ends**, it files what was said.
+
+Behind the mod is a program of its own, the `dream` command, with an archive, a daily run, and checks that everything the dream writes to memory has to pass.
+
+```mermaid
+flowchart TB
+    subgraph inside["Inside Claude Code"]
+        session(["Your session"])
+        mod["The remcycle mod<br/>hooks, three tools, a panel"]
+        own[("Claude Code's<br/>own memory")]
+    end
+    subgraph machine["On your machine"]
+        dream{{"The dream command"}}
+        archive[("Archive<br/>every session")]
+        copy[("The dream's copy<br/>of memory")]
+        night(["Once a day,<br/>from a session"])
+    end
+    model(["The model, through<br/>your own Claude Code"])
+    session <--> mod
+    mod -- "asks, and files sessions" --> dream
+    night --> dream
+    dream <--> archive
+    dream <--> copy
+    dream -- "new sessions" --> model
+    dream -. "only when you publish" .-> own
+```
+
+## What it does without asking
+
+Once installed, it saves what was said when a session ends, hands each new session what was learned, and once a day starts the dream in the background to read the new sessions. The dream is the part that uses your Claude plan, and `dream daily off`, or the switch in the panel, turns it off.
+
+Four things never happen without you: writing into the memory Claude Code itself loads, retiring or replacing a note you already had, deleting anything from the archive, and reading a project you have excluded.
+
+## Find out more
+
+- [How it works](https://github.com/lianmatsuo/remcycle/blob/main/docs/how-it-works.md): the idea, in plain words and pictures.
+- [Reference](https://github.com/lianmatsuo/remcycle/blob/main/docs/reference.md): every command and setting.
+- [The daily dream](https://github.com/lianmatsuo/remcycle/blob/main/docs/schedule.md): its settings, and running it at a fixed time instead.
+- [Design notes](https://github.com/lianmatsuo/remcycle/blob/main/docs/intent.md): why it is built this way, and what was rejected.
+- [Privacy](https://github.com/lianmatsuo/remcycle/blob/main/PRIVACY.md): what it keeps on your machine, and what leaves it.
+
+## Status
+
+This is early software, written for one person's machine and released as it stands. It reads Claude Code's transcripts and, when you ask it to, writes to the memory Claude Code loads, so read what a command will do before you run it.
+
+It runs on macOS and Linux; Windows is untested. The mod needs Claude Code 2.1.287 or later in the terminal, or 2.1.286 in the desktop app.
+
+remcycle is an independent project and is not affiliated with or endorsed by Anthropic.
+
+## Development
+
+```bash
+scripts/check
+```
+
+That runs everything CI runs: the Python lint and tests, the mod's manifest, types and tests, and the subjects of the branch's commits. [CONTRIBUTING.md](https://github.com/lianmatsuo/remcycle/blob/main/CONTRIBUTING.md) says how to start, and [AGENTS.md](https://github.com/lianmatsuo/remcycle/blob/main/AGENTS.md) is the working guide for people and coding agents alike.
+
+The Python tests sit at these seams: transcript parsing, the archive against a real SQLite file, settings, reconciliation as pure functions, the memory store against folders in Claude Code's format, extraction through a stand-in for the model, the gate, and whole dream runs against temporary folders.
+
+The mod's tests run in Claude Code's own plugin test kit, so that half of the check needs Claude Code installed.
+
+## Licence
+
+Apache-2.0. See [LICENSE](https://github.com/lianmatsuo/remcycle/blob/main/LICENSE). Copyright 2026 Lian Matsuo, as [NOTICE](https://github.com/lianmatsuo/remcycle/blob/main/NOTICE) says.

remcycle-0.3.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "remcycle"
+version = "0.3.0"
+description = "Garbage collection for Claude Code's memory: rereads your sessions every day, keeps what you decided, and questions stale notes"
+dynamic = ["readme"]
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.12"
+authors = [{ name = "Lian Matsuo" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/lianmatsuo/remcycle"
+Changelog = "https://github.com/lianmatsuo/remcycle/blob/main/CHANGELOG.md"
+Issues = "https://github.com/lianmatsuo/remcycle/issues"
+
+[project.scripts]
+dream = "dream.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.16.10",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-fancy-pypi-readme>=25.1"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dream"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/CHANGELOG.md"]
+
+# PyPI shows the README away from the repository, so its links and pictures are given in full.
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\]\((?!https?://|#)([^)]+)\)'
+replacement = '](https://github.com/lianmatsuo/remcycle/blob/main/\1)'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = 'href="(?!https?://|#)([^"]+)"'
+replacement = 'href="https://github.com/lianmatsuo/remcycle/blob/main/\1"'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = 'src="(?!https?://)([^"]+)"'
+replacement = 'src="https://raw.githubusercontent.com/lianmatsuo/remcycle/main/\1"'
+
+[tool.ruff]
+# Wide enough for the lines the code already has, so sorting imports does not rewrap them.
+line-length = 160
+# So imports of the package and of the tests' own helpers sort as this project's.
+src = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]