astern 0.0.6__tar.gz

astern-0.0.6/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Permissions: the reusable workflow needs `contents: write` (version-bump
+# push-back, gh-pages branch push) and `pages: write` (Pages REST config).
+# Both default to read-only on personal-account callers, so they are granted
+# explicitly here.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`, which does not reliably
+    # propagate caller-repo secrets to a reusable workflow owned by a different
+    # account). astern reads local files and only ever runs the local `claude` CLI, so
+    # PYPI_PASSWORD is the only secret it needs.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

astern-0.0.6/.gitignore

@@ -0,0 +1,132 @@
+docs/_build/
+wads_configs.json
+data/wads_configs.json
+wads/data/wads_configs.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea
+
+# Ruff
+.ruff_cache/
+
+# VS Code
+.vscode/
+
+# Temporary test outputs
+batch_results.json
+*.tmp
+tmp/
+temp/
+# Local session handoffs (not for commit)
+.claude/handoffs/
+
+# Session worktrees created by `claude --worktree` (not for commit)
+.claude/worktrees/

astern-0.0.6/LICENSE

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

astern-0.0.6/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: astern
+Version: 0.0.6
+Summary: Look astern: mine your past Claude Code sessions for recurring problems, friction, rewritten code, and the vocabulary gap between you and your agents
+Project-URL: Homepage, https://github.com/thorwhalen/astern
+Project-URL: Repository, https://github.com/thorwhalen/astern
+Project-URL: Issues, https://github.com/thorwhalen/astern/issues
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,mining,retrospective,sessions,transcripts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: cw<0.2,>=0.1.1
+Requires-Dist: dol>=0.3
+Requires-Dist: openloops>=0.1.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: recall
+Requires-Dist: ir>=0.1.31; extra == 'recall'
+Provides-Extra: similar
+Requires-Dist: ir; extra == 'similar'
+Description-Content-Type: text/markdown
+
+# astern
+
+`crowsnest` watches the sessions running right now; `astern` looks back at the wake they left — the transcripts Claude Code already keeps under `~/.claude/projects/`. It mines them for what problems recur, where agents get stuck, what one-off code keeps being rewritten, and which words you and your agents don't share, without spending a token twice.
+
+## Start here
+
+```bash
+pip install astern
+
+astern sync                        # read new or changed transcripts, run the free (heuristic) lenses
+astern sessions                    # what's synced, newest first
+astern show <sid-prefix>           # one session: meta, ledger state, last turns, findings
+astern report friction             # (in progress) a lens's findings as a markdown report
+astern judge                       # (in progress) run the LLM-judged lenses over what's synced
+astern estimate                    # (in progress) token/cost estimate before a judge batch runs
+
+pip install "astern[recall]"       # + ir, for searching what past sessions already know
+astern index                       # index the store into ir corpora (idempotent)
+astern recall "what did we decide about the ledger"    # ...and ask it
+astern install-skills              # link the shipped skills into ~/.claude/skills
+```
+
+`sync`, `sessions` and `show` are shipped today. `report`, `judge` and `estimate` are being built out by other agents against the same store and ledger; once they land, the one-command loop is `astern sync && astern judge && astern report friction`.
+
+## What it extracts
+
+Each **lens** asks one question of a session and returns typed, evidence-backed findings — every finding points back at the turn it came from. Method: **H** = deterministic heuristic, zero tokens; **L** = LLM-judged, spends subscription tokens via the local `claude` CLI; **H→L** = a heuristic shortlist that only the survivors get judged on.
+
+| Lens | Question | Method |
+|---|---|---|
+| `stats` | The shape of a session in numbers — the cost model's own features | H |
+| `problems` | What problem was each session solving, and how was it solved? | L |
+| `recurring` | Which problems recur, and would a skill or subagent pay for itself? | H over L |
+| `rewrites` | What one-off code keeps being rewritten? | H→L |
+| `friction` | Where do agents get stuck, and what would remove the obstacle? | H→L |
+| `jargon-in` | Which of my phrasings point to an established term I don't use? | L |
+| `jargon-out` | Which terms do agents use that I don't? | H→L |
+| `corrections` | What did I correct or re-affirm, and which corrections repeat? | H→L |
+| `prompt-quality` | Which prompt shapes lead to clean turns, which to flailing ones? | H→L |
+| `cost` | Where do the tokens and hours go, by project / task / model? | H |
+| `timeline` | What did I work on this week, and what landed? | H→L |
+| `decisions` | Which decisions were made, and why? | L |
+| `claims` | Where did an agent claim "done" and a later turn show otherwise? | H→L |
+| `questions` | What do agents keep asking me, and what did I answer? | H→L |
+| `tooling` | Which skills/subagents/MCP tools are used, unused, or missing? | H |
+| `memory-candidates` | Which restated facts should become memory, and where does memory drift? | H→L |
+| `evals` | Which (prompt, outcome) pairs make a regression test for a skill? | H |
+| `hygiene` | Do agents read before they edit, and does that change over time? | H |
+| `regression` | Did the harness or model change behaviour? | H |
+| `adherence` | Which CLAUDE.md/skill rules are followed, ignored, or fought? | L |
+| `subagents` | Which subagent / `Workflow` spawns paid for themselves? | H |
+| `effect` | Did an adopted rule, skill or function reduce the pattern it targeted? | H |
+
+Session handoffs (`Q`) are deliberately not a lens here — that's `openloops`, linked rather than re-derived. The full catalogue, with the signal each lens reads and the sink it feeds, is plan §2 (see "The seams" below).
+
+## Recall — what past sessions already know
+
+`astern recall "<query>"` answers *what did we already think, try and decide about X* without re-reading a transcript. astern is only the **record source** here: `ir` owns the indexing and the search, and the multi-hop search loop belongs to `raglab`. Install the extra (`pip install "astern[recall]"`), run `astern index` after a `sync`, and ask.
+
+Two grains, indexed as two `ir` corpora because they answer different questions:
+
+| Corpus | One record is | Best for |
+|---|---|---|
+| `session_synopses` | a whole session as the `synopsis` lens distilled it — goal, problems and solutions, decisions, corrections | **what was decided** |
+| `session_turns` | one turn: the prompt and the assistant's closing text | **what was actually tried** |
+
+Unfiltered, a recall also reaches the `skills` and `reports` corpora when this machine has them (weighted below the sessions, so they inform rather than crowd out). `--project X` and `--since-days N` are hard metadata filters; a project is resolved *through the store* into its session ids, because a session about a project often runs from a group dir or a worktree whose name says nothing about it.
+
+Embedding is local and offline: ir's `all-MiniLM-L6-v2` by default — **no API key, no per-query cost** — with `--embedder light` (numpy-only hashing) for a build with no model download. Each hit carries a `pointer`, the `astern show` command that fetches the full record: a hit is an address, not an answer. The shipped `astern-recall` skill drives the whole loop, ending in a briefing written to the repo the question was about.
+
+`episodes` — a third grain, consecutive turns on one topic — is deliberately not built yet (issue #7).
+
+## Never spending a token twice
+
+Every lens run goes through the **ledger**: one entry per session, keyed on the transcript file's fingerprint (size + mtime) and, per lens, its version and the last turn index it has seen. From that, `ledger.plan()` picks one of three actions:
+
+- **skip** — this lens version already covered every turn that exists in the transcript.
+- **incremental** — the session grew (it was resumed); only lenses that declare `incremental=True` get handed just the new turns (`from_index` onward) plus their own prior findings, and extend rather than redo.
+- **full** — never analyzed, or analyzed by an older lens version; everything is reprocessed.
+
+A heuristic lens (`kind='H'`) costs nothing, so paying for `full` on every source change is fine. The ledger earns its keep on the LLM lenses (`kind='L'`): a resumed session must not pay again for turns it already paid for, and `astern sync` never re-reads a transcript whose size and mtime it already has on file.
+
+## Where things live
+
+The store is `dol`-backed JSON files under `~/.local/share/astern/` (`sessions`, `turns`, `findings`, `ledger`, `judgments`) — override with `$ASTERN_DATA_DIR` to keep an experiment out of the real store. The transcripts it reads come from `~/.claude` by default — override with `$ASTERN_HOME` to point at a second account or a synced copy of another machine's home. Both are seams: any `MutableMapping` serves as a store, and `homes()` takes a single dir, an iterable of dirs, or `None`.
+
+## The seams
+
+Five things in astern are deliberately swappable, each with a strong out-of-the-box default and a named replacement:
+
+| Seam | v1 default | Replacement |
+|---|---|---|
+| `home=` — which `~/.claude`-shaped dirs to read | the one `~/.claude` | a second account, or the server's home over a sync |
+| `store=` — where records and findings live | `dol` JSON files under `~/.local/share/astern/` | any `MutableMapping` — S3, SQLite, a dict for tests |
+| `judge=` — the LLM callable for `L` lenses | the local `claude` CLI, headless, no session persisted | `aix.prompt_func` for API billing; a recorded-replay judge for tests |
+| `similar=` — how findings group across sessions | normalized-string near match | `ir` corpus + embeddings, for real semantic clustering |
+| `turns=` — the transcript-to-turns fetcher | astern's own `openloops`-backed iterator | `priv.claude_transcripts.turn_pair_records` by injection |
+| `embedder=` — how `astern index` embeds | `ir`'s local `all-MiniLM-L6-v2` (offline, no key) | `light` (numpy-only), or any embedder spec `ir` understands |
+
+What's deliberately **not** a seam: the lens registry (a module-level dict), report templates, the finding dict shape, and the `openloops.egress` scrub step on every sink — none of these are meant to vary.
+
+## Not in astern
+
+- **Live sessions** — that's `crowsnest`'s axis (*this minute*), not astern's (*the wake*).
+- **Obligation tracking** — what's owed, blocked, or open — that's `openloops`.
+- **Transcript viewers, full-text search, cost dashboards** — `claude-code-log`, `cc-transcript`, `episodic-memory` and `ccusage` already do these well; install them alongside astern rather than rebuilding them here.
+- **Writing into `CLAUDE.md`, skills, or memory.** Every lens emits *candidates* — mined skill/rule/function/memory suggestions — for a human to accept through `skill`, `opsward`, `coact`, or `ge.memory`. Nothing here writes automatically; that's the same "report, never repair" invariant `priv upkeep` carries.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q                            # the test suite
+pytest --doctest-modules astern      # every module's own doctest
+```

astern-0.0.6/README.md

@@ -0,0 +1,115 @@
+# astern
+
+`crowsnest` watches the sessions running right now; `astern` looks back at the wake they left — the transcripts Claude Code already keeps under `~/.claude/projects/`. It mines them for what problems recur, where agents get stuck, what one-off code keeps being rewritten, and which words you and your agents don't share, without spending a token twice.
+
+## Start here
+
+```bash
+pip install astern
+
+astern sync                        # read new or changed transcripts, run the free (heuristic) lenses
+astern sessions                    # what's synced, newest first
+astern show <sid-prefix>           # one session: meta, ledger state, last turns, findings
+astern report friction             # (in progress) a lens's findings as a markdown report
+astern judge                       # (in progress) run the LLM-judged lenses over what's synced
+astern estimate                    # (in progress) token/cost estimate before a judge batch runs
+
+pip install "astern[recall]"       # + ir, for searching what past sessions already know
+astern index                       # index the store into ir corpora (idempotent)
+astern recall "what did we decide about the ledger"    # ...and ask it
+astern install-skills              # link the shipped skills into ~/.claude/skills
+```
+
+`sync`, `sessions` and `show` are shipped today. `report`, `judge` and `estimate` are being built out by other agents against the same store and ledger; once they land, the one-command loop is `astern sync && astern judge && astern report friction`.
+
+## What it extracts
+
+Each **lens** asks one question of a session and returns typed, evidence-backed findings — every finding points back at the turn it came from. Method: **H** = deterministic heuristic, zero tokens; **L** = LLM-judged, spends subscription tokens via the local `claude` CLI; **H→L** = a heuristic shortlist that only the survivors get judged on.
+
+| Lens | Question | Method |
+|---|---|---|
+| `stats` | The shape of a session in numbers — the cost model's own features | H |
+| `problems` | What problem was each session solving, and how was it solved? | L |
+| `recurring` | Which problems recur, and would a skill or subagent pay for itself? | H over L |
+| `rewrites` | What one-off code keeps being rewritten? | H→L |
+| `friction` | Where do agents get stuck, and what would remove the obstacle? | H→L |
+| `jargon-in` | Which of my phrasings point to an established term I don't use? | L |
+| `jargon-out` | Which terms do agents use that I don't? | H→L |
+| `corrections` | What did I correct or re-affirm, and which corrections repeat? | H→L |
+| `prompt-quality` | Which prompt shapes lead to clean turns, which to flailing ones? | H→L |
+| `cost` | Where do the tokens and hours go, by project / task / model? | H |
+| `timeline` | What did I work on this week, and what landed? | H→L |
+| `decisions` | Which decisions were made, and why? | L |
+| `claims` | Where did an agent claim "done" and a later turn show otherwise? | H→L |
+| `questions` | What do agents keep asking me, and what did I answer? | H→L |
+| `tooling` | Which skills/subagents/MCP tools are used, unused, or missing? | H |
+| `memory-candidates` | Which restated facts should become memory, and where does memory drift? | H→L |
+| `evals` | Which (prompt, outcome) pairs make a regression test for a skill? | H |
+| `hygiene` | Do agents read before they edit, and does that change over time? | H |
+| `regression` | Did the harness or model change behaviour? | H |
+| `adherence` | Which CLAUDE.md/skill rules are followed, ignored, or fought? | L |
+| `subagents` | Which subagent / `Workflow` spawns paid for themselves? | H |
+| `effect` | Did an adopted rule, skill or function reduce the pattern it targeted? | H |
+
+Session handoffs (`Q`) are deliberately not a lens here — that's `openloops`, linked rather than re-derived. The full catalogue, with the signal each lens reads and the sink it feeds, is plan §2 (see "The seams" below).
+
+## Recall — what past sessions already know
+
+`astern recall "<query>"` answers *what did we already think, try and decide about X* without re-reading a transcript. astern is only the **record source** here: `ir` owns the indexing and the search, and the multi-hop search loop belongs to `raglab`. Install the extra (`pip install "astern[recall]"`), run `astern index` after a `sync`, and ask.
+
+Two grains, indexed as two `ir` corpora because they answer different questions:
+
+| Corpus | One record is | Best for |
+|---|---|---|
+| `session_synopses` | a whole session as the `synopsis` lens distilled it — goal, problems and solutions, decisions, corrections | **what was decided** |
+| `session_turns` | one turn: the prompt and the assistant's closing text | **what was actually tried** |
+
+Unfiltered, a recall also reaches the `skills` and `reports` corpora when this machine has them (weighted below the sessions, so they inform rather than crowd out). `--project X` and `--since-days N` are hard metadata filters; a project is resolved *through the store* into its session ids, because a session about a project often runs from a group dir or a worktree whose name says nothing about it.
+
+Embedding is local and offline: ir's `all-MiniLM-L6-v2` by default — **no API key, no per-query cost** — with `--embedder light` (numpy-only hashing) for a build with no model download. Each hit carries a `pointer`, the `astern show` command that fetches the full record: a hit is an address, not an answer. The shipped `astern-recall` skill drives the whole loop, ending in a briefing written to the repo the question was about.
+
+`episodes` — a third grain, consecutive turns on one topic — is deliberately not built yet (issue #7).
+
+## Never spending a token twice
+
+Every lens run goes through the **ledger**: one entry per session, keyed on the transcript file's fingerprint (size + mtime) and, per lens, its version and the last turn index it has seen. From that, `ledger.plan()` picks one of three actions:
+
+- **skip** — this lens version already covered every turn that exists in the transcript.
+- **incremental** — the session grew (it was resumed); only lenses that declare `incremental=True` get handed just the new turns (`from_index` onward) plus their own prior findings, and extend rather than redo.
+- **full** — never analyzed, or analyzed by an older lens version; everything is reprocessed.
+
+A heuristic lens (`kind='H'`) costs nothing, so paying for `full` on every source change is fine. The ledger earns its keep on the LLM lenses (`kind='L'`): a resumed session must not pay again for turns it already paid for, and `astern sync` never re-reads a transcript whose size and mtime it already has on file.
+
+## Where things live
+
+The store is `dol`-backed JSON files under `~/.local/share/astern/` (`sessions`, `turns`, `findings`, `ledger`, `judgments`) — override with `$ASTERN_DATA_DIR` to keep an experiment out of the real store. The transcripts it reads come from `~/.claude` by default — override with `$ASTERN_HOME` to point at a second account or a synced copy of another machine's home. Both are seams: any `MutableMapping` serves as a store, and `homes()` takes a single dir, an iterable of dirs, or `None`.
+
+## The seams
+
+Five things in astern are deliberately swappable, each with a strong out-of-the-box default and a named replacement:
+
+| Seam | v1 default | Replacement |
+|---|---|---|
+| `home=` — which `~/.claude`-shaped dirs to read | the one `~/.claude` | a second account, or the server's home over a sync |
+| `store=` — where records and findings live | `dol` JSON files under `~/.local/share/astern/` | any `MutableMapping` — S3, SQLite, a dict for tests |
+| `judge=` — the LLM callable for `L` lenses | the local `claude` CLI, headless, no session persisted | `aix.prompt_func` for API billing; a recorded-replay judge for tests |
+| `similar=` — how findings group across sessions | normalized-string near match | `ir` corpus + embeddings, for real semantic clustering |
+| `turns=` — the transcript-to-turns fetcher | astern's own `openloops`-backed iterator | `priv.claude_transcripts.turn_pair_records` by injection |
+| `embedder=` — how `astern index` embeds | `ir`'s local `all-MiniLM-L6-v2` (offline, no key) | `light` (numpy-only), or any embedder spec `ir` understands |
+
+What's deliberately **not** a seam: the lens registry (a module-level dict), report templates, the finding dict shape, and the `openloops.egress` scrub step on every sink — none of these are meant to vary.
+
+## Not in astern
+
+- **Live sessions** — that's `crowsnest`'s axis (*this minute*), not astern's (*the wake*).
+- **Obligation tracking** — what's owed, blocked, or open — that's `openloops`.
+- **Transcript viewers, full-text search, cost dashboards** — `claude-code-log`, `cc-transcript`, `episodic-memory` and `ccusage` already do these well; install them alongside astern rather than rebuilding them here.
+- **Writing into `CLAUDE.md`, skills, or memory.** Every lens emits *candidates* — mined skill/rule/function/memory suggestions — for a human to accept through `skill`, `opsward`, `coact`, or `ge.memory`. Nothing here writes automatically; that's the same "report, never repair" invariant `priv upkeep` carries.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q                            # the test suite
+pytest --doctest-modules astern      # every module's own doctest
+```

astern-0.0.6/astern/__init__.py

@@ -0,0 +1,26 @@
+"""astern — look astern: mine your past Claude Code sessions.
+
+The crow's nest (``crowsnest``) watches the sessions that are running now; astern
+looks back at the wake they left. It reads the transcripts Claude Code already writes,
+keeps its own store of turns and findings, and answers, without spending tokens twice:
+what problems recur, where agents get stuck, what one-off code keeps being rewritten,
+what words you and your agents do not share.
+
+Core contract: :mod:`astern.tools` (plain functions, JSON in, JSON out) over
+:mod:`astern.sources` → :mod:`astern.turns` → :mod:`astern.store` with
+:mod:`astern.ledger` deciding what still needs analyzing, :mod:`astern.lenses`
+answering the questions, and :mod:`astern.judge` the one LLM seam.
+"""
+
+from astern.judge import Judgment, claude_judge, replay_judge  # noqa: F401
+from astern.lenses import LENSES, finding, lens  # noqa: F401
+from astern.store import MemoryStore, Store, mk_store  # noqa: F401
+from astern.tools import install_skills, lenses, sessions, show, sync  # noqa: F401
+
+# `recall` and `index` are deliberately NOT re-exported here: binding them on the
+# package would shadow the :mod:`astern.recall` module, and `import astern.recall
+# as r` would then hand back a *function* — a trap that fails much later than it
+# is made. Reach them as `from astern.recall import recall, index` (or through
+# :mod:`astern.tools`, which is what the CLI dispatches).
+
+__version__ = "0.0.1"

astern-0.0.6/astern/__main__.py

@@ -0,0 +1,13 @@
+"""``astern`` command line: ``cw`` over the functions :mod:`astern.tools` exposes."""
+
+import cw
+
+from astern.tools import _dispatch_funcs
+
+
+def main():
+    raise SystemExit(cw.dispatch(_dispatch_funcs))
+
+
+if __name__ == "__main__":
+    main()

astern-0.0.6/astern/data/skills/astern-recall/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: astern-recall
+description: >-
+  Search past Claude Code sessions for what was already thought, tried and
+  decided about a topic, and write the answer up as a briefing. Use when the
+  user asks "what did we decide about X", "what did I already try for X", "did
+  we ever look at X", "why did we do X that way", "catch me up on project X",
+  "what happened last time I worked on X", or "before I start on X, what do past
+  sessions say" — and use it proactively at the start of work on a project the
+  user has not touched in weeks, before re-deriving a decision that a past
+  session already made. Runs astern's mined session store (sync → index →
+  recall) through the `ir` retrieval substrate; reads the few hits that matter
+  with `astern show`; writes `docs/briefings/<date>-<slug>.md` in the repo the
+  question is about. Read-only with respect to the sessions themselves.
+metadata:
+  audience: developers
+---
+
+# astern recall — what past sessions already know
+
+Transcripts are the only honest record of why a project is the way it is, and nobody re-reads them. `astern` mines them into a store; this skill turns that store into an answer.
+
+**What it is not**: a chat log search. A hit is an *address*, not an answer — the procedure below ends with you reading the top hits and writing a briefing, because the value is in the synthesis, not in the ranked list.
+
+## Prerequisites (check once, cheap)
+
+```bash
+astern sessions --limit 3     # is anything synced at all?
+```
+
+If that errors on an import, the retrieval extra is missing: `pip install "astern[recall]"` (it pulls `ir`, `ef`, `vd`). No API key is needed — the default embedder is local and offline.
+
+## Procedure
+
+### 1. Sync and index (both idempotent — run them, don't ask)
+
+```bash
+astern sync                   # read new/changed transcripts into the store
+astern index                  # build the ir corpora (only what changed is embedded)
+```
+
+`sync` reads only transcripts whose size/mtime changed; `index` embeds only records whose content hash changed. Running both costs seconds when nothing moved. Do not skip `index` after a `sync`: an index built yesterday answers confidently about a corpus that no longer matches.
+
+### 2. Recall
+
+```bash
+astern recall "how do we keep the miner from re-judging a resumed session"
+astern recall "what did we decide about the judge and json schema retries" --project astern
+astern recall "vector store backend choice" --project vd --since-days 120 --k 12
+```
+
+Flags: `--project` (matched against the session's project/cwd), `--since-days`, `--k` (how many hits), `--grains session_synopses|session_turns` (default both), `--mode dense|lexical|hybrid` (default hybrid).
+
+Two grains answer different questions, and it is worth naming which you want:
+
+| Grain | One record is | Best for |
+|---|---|---|
+| `session_synopses` | a whole session, LLM-distilled: goal, problems and their solutions, decisions, corrections | **what was decided**, what the session was for |
+| `session_turns` | one turn: the prompt and the assistant's closing text | **what was actually tried**, the specific error, the exact command |
+
+Unfiltered, recall also reaches the `skills` and `reports` corpora when this machine has them — often the fastest route to an existing skill or a written-up report. A `--project` or `--since-days` filter deliberately excludes those two (they carry no project or timestamp metadata); the result's `notes` says so.
+
+If `abstained` is true or the hits look unrelated, **reformulate rather than reporting nothing**: try the vocabulary a session would have used (an error message, a file name, a command) and `--mode lexical` for identifier-heavy queries. Two or three query shapes is normal; that loop is your job, not the tool's.
+
+### 3. Read the hits that matter
+
+Every hit carries a `pointer` — run it:
+
+```bash
+astern show <session_id>              # the session's meta + its last turns
+astern show <session_id> --turns 40   # more of the turn history
+```
+
+Read the top 3–6. A synopsis hit tells you a decision was made; the turns tell you what it actually was and whether it stuck. Where they disagree, the turns win — a synopsis is a summary, and later turns may have reversed it.
+
+### 4. Write the briefing
+
+Write to **the repo the question is about** (not astern's), at `docs/briefings/<YYYY-MM-DD>-<slug>.md`. Create the directory if it does not exist. Then tell the user the path.
+
+Rules for the file:
+
+- **No hard-wrapped prose.** One line per paragraph or list item — newlines only where markdown is structural.
+- **Cite every claim**: the session id (first 8 chars is enough) and the date. A briefing whose claims cannot be traced back is a rumour.
+- **Separate what was DECIDED from what was merely TRIED.** This is the whole point. A decision is something the user stated or ratified; an experiment an agent ran and abandoned is not a decision, however confidently the transcript reads.
+- **Say what you did not find.** An absence ("no session discusses the S3 backend") is a finding, and it is what stops the reader from assuming you looked and hid it.
+
+Shape:
+
+```markdown
+# <Topic> — what past sessions say
+
+_Briefing written <date> from N sessions between <first> and <last>. Sources: astern session ids, cited inline._
+
+## Decided
+
+- <the decision>, stated in `a1b2c3d4` (2026-07-14) and unchanged since.
+
+## Tried, not settled
+
+- <the approach>, attempted in `e5f6a7b8` (2026-08-02); abandoned after <what happened>.
+
+## Open questions
+
+- <what nobody answered>
+
+## Not found
+
+- <what you searched for and did not find, with the queries you used>
+```
+
+## Notes
+
+- **Never paste real transcript content into a public artifact** (an issue, a PR, a committed doc that leaves the machine) without checking it for secrets and absolute home paths. A briefing is a local doc; keep it that way unless the user says otherwise.
+- The store is per-machine. A second Claude home (`~/.claude-*`) is just another source to `astern sync`; a session that lives only on another machine is invisible here, and "not found" means "not found on this machine".
+- `episodes` — a third grain, consecutive turns on one topic — does not exist yet (thorwhalen/astern#7). Until it does, a topic that spans many turns is best reached through `session_synopses` first, then read in full with `astern show`.