shapa 0.9.0__tar.gz

shapa-0.9.0/AGENTS.md

@@ -0,0 +1,62 @@
+# shapa-llm
+
+Source of the `shapa` tool: an operational-memory engine for LLM agents (one SQLite database per wiki holding the work ledger and memory/rule/issue rows, ranked recall, self-healing maintenance). This file is for agents working on the tool itself. The note schema a wiki follows is `shapa/assets/AGENTS.md`, which `shapa init` installs into every wiki; this repo's own wiki is `.shapa/`.
+
+## Navigation
+
+- `shapa/` is the engine package; `cli.py` is the `shapa` command (`python3 -m shapa` from a clone).
+  - Wiki resolution and discovery: `config.py`, `registry.py` (`~/.shapa/wikis.json`).
+  - Read path: `bootstrap.py` (SessionStart), `fetch.py`, `rank.py`, `bm25.py`, `embed.py`, `get.py`.
+  - Database (format 4): `db.py` (schema, work ledger, rows, sweep, worktree resolution), `ledger.py` (`shapa ledger`/`row`/`correction` and the git and harness triggers), `migrate4.py` (format 3 to 4), `commit.py` (`shapa commit`: the wiki commits itself on the default branch, as a SessionEnd/SessionStart hook).
+  - Write path: `capture.py` (Stop hook), `redact.py`, `memlog.py` (format-3 log, and the derived index that also mirrors database rows), `save.py`.
+  - Index and daemon: `store.py`, `serve.py`. MCP server: `mcp.py`.
+  - Maintenance: `maintain.py`, `heartbeat.py`, `score.py`. Format: `frontmatter.py`, `nodes.py`, `validate.py`, `upgrade.py`, `status.py`, `reconfigure.py` (the session-start restructure directive; its prompt is `assets/prompts/reconfigure.md`). Opt-in importer: `memri_import.py`.
+- `shapa/assets/` ships into user wikis: `AGENTS.md` (schema and wiki marker), `placement.md`, the `arch/index.md` template, and `skills/shapa-upgrade` (installed into harnesses, never into a wiki).
+- `tests/` is the pytest suite, with fixtures under `tests/fixtures/`.
+- `install.sh` wires hooks, MCP and the skill from a clone. `bootstrap.sh` is the `curl | sh` installer.
+- `.shapa/` is this repo's wiki: `shapa.db` holds its work ledger and rows (`shapa ledger`, `shapa row list`), `arch/` the design docs.
+- `.github/workflows/test.yml` is CI.
+
+## Owner
+
+Roukh (github.com/Roukh/shapa-llm), sole maintainer, MIT license. Commits use the Roukh noreply identity, and pushes need the `Roukh` gh account active (`gh auth status`). Work is tracked in this repo's ledger (`shapa ledger`).
+
+## Commands
+
+- Tests: `.venv/bin/python -m pytest -q`. In a network-sandboxed shell, `tests/test_serve.py` (Unix sockets) and `tests/test_installer_upgrade.py` fail; run those outside the sandbox before calling the suite green.
+- CI runs `python -m pytest -q` on Python 3.11, 3.12 and 3.13, once on the bare core install and once with `[semantic,mcp]`.
+- Install the live CLI from this checkout: `uv tool install --force '.[semantic,mcp]'` from the repo root, then `shapa upgrade --all --check`.
+- Health: `shapa doctor` (exits 1 when the install needs a hand - a wiki behind format, this repo's git hooks not wired, no agent harness connected), `shapa status` (same report, never exits 1), `shapa validate`.
+- Before checking a wheel's contents, delete `build/`; a stale one re-ships files removed from `shapa/assets/`.
+
+## Boundaries
+
+- The repo is public. Everything tracked, `.shapa/` included, is published on push. Keep secrets, client names, other projects' details and private wiki content out of code, tests, fixtures, notes and commit messages.
+- The core engine stays pure standard library (`dependencies = []` in `pyproject.toml`). A new dependency goes behind an optional extra, and the core path must still work without it.
+- The engine has no hosted-database or hosted-service coupling; its one database is the local `shapa.db` file. Integrations with other systems live outside this repo.
+- Never run `shapa maintain --prune` or a non-dry-run heartbeat against a live wiki from an agent session; use `--dry-run`. Prune is operator-run only.
+- Destructive paths never trust frontmatter an agent wrote: `arch/` is protected by path, and superseded note files move to `archive/`. Database rows are different by design: the after-feature sweep deletes closed, expired, duplicate, superseded and stale rows, and the database file's git history is the record.
+- A wiki database is committed only on the default branch - `shapa commit` does this itself at session end (SessionEnd hook, with SessionStart as a catch-up for a crashed session), scrubbing any configured terms first; `shapa ledger pre-commit` still refuses a manual commit of it elsewhere. Worktrees write and commit through the primary checkout's file.
+- Only `shapa init --global` may write the global wiki pointer (`~/.shapa/config.json`).
+- `capture` and `maintain` run as hooks: they never block a session (always exit 0) and never write inside this repo or the installed package.
+- Tests run against temporary wikis. `tests/conftest.py` points `$SHAPA_REGISTRY` at a throwaway file; never aim the suite at a real wiki.
+- A headless `claude -p` call from the engine passes empty hooks (`--settings '{"hooks":{}}'`) and closed stdin.
+
+## Dependencies
+
+- Runtime: Python 3.11 or newer, standard library only.
+- Optional extras: `[semantic]` adds `model2vec>=0.3.0` (the potion-base-8M model, loaded from the local cache with no hub round-trip) for fused vector plus BM25 recall; `[mcp]` adds `mcp>=1.0.0`, and `shapa mcp` falls back to a stdlib JSON-RPC shim without it. `[embeddings]` is a deprecated alias of `[semantic]`.
+- Dev: `pytest`, in the repo's `.venv`.
+- Touched by the installers: Claude Code `settings.json`, `~/.codex/config.toml`, `opencode.json` (merged with `jq`), and Obsidian when present. `maintain --resolve` shells out to the `claude` CLI.
+- State outside the repo: `~/.shapa/config.json` (global pointer), `~/.shapa/wikis.json` (registry), `$SHAPA_MEMORY` (override).
+
+## Contracts
+
+Current:
+- A wiki is a `.shapa/` or `shapa/` directory holding `AGENTS.md`, found by walking up from the cwd (`.shapa/` first). `config.memory_dir()` resolves `$SHAPA_MEMORY`, then the discovered wiki, then the pointer, then `~/.shapa/memory`.
+- A bare `shapa init` resolves the git top level (the PRIMARY checkout's, from a linked worktree) and creates `.shapa/` there - or respects a legacy `shapa/` already there - then links this repo's git hooks (`shapa/githooks.py`: never into a shared or hook-manager-owned dir it doesn't own). Only `--global` records the global pointer; `--obsidian` opts into the Obsidian vault.
+- Reads fan out over the global and repo wikis in scope; writes are scope-gated (`save --scope global|repo|external`).
+- Wiki format 4: `shapa.db` (tracked, committed whole) is the source of truth for the work ledger (features, jobs, tasks) and memory/rule/issue rows. `.shapa-index.db` (FTS5, vectors, use counters) is derived and gitignored and mirrors the rows for recall. `arch/` and `research/` stay files; `temp/<feature>/` is gitignored scrap. `.shapa-format` marks a wiki's format, and `shapa upgrade` migrates older wikis.
+- Recall mode is `fused` with `[semantic]` and `bm25` without it, and every surface reports which.
+
+Historical (do not resurrect): the format-3 `memory/*.jsonl` log, `checklist.md`, `agenda.md` and `ideas.md` as wiki files (replaced by the database in format 4), memory kept only outside the repo (v0.6), the `uses` frontmatter counter, `sentence-transformers` embeddings, the single repo-root wiki with no global/repo split (2026-07-10), one md note per captured session (before 0.8.0), and a `shapa search` command (0.8.0 has `fetch`). Superseded specs live in git history.

shapa-0.9.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.9.0] - 2026-10-08
+
+### Added
+
+- `shapa init`, run inside a git repo, creates `.shapa/` at the git top
+  level from any subdirectory. A linked worktree initializes the primary
+  checkout. Outside git, `init` stops with a message; `--no-git` creates
+  `./.shapa` instead. Obsidian scaffolding is opt-in behind `--obsidian`.
+  `init` installs the repo's git pre-commit and post-commit hooks and
+  prints what happens next, without touching any file outside `.shapa/`.
+  It never writes into a shared or global `core.hooksPath`, or into hooks
+  owned by husky, lefthook or the pre-commit framework; it prints the
+  lines to add instead.
+- `shapa doctor` checks the global wiki, the repo wiki, git hooks, and
+  every connected harness: Claude Code hooks and MCP, Codex MCP, OpenCode
+  MCP. It also confirms the `shapa` command resolves, and exits 1 listing
+  each problem with its fix command. `shapa status` shows the same
+  report.
+- `shapa commit [--hook] [--dry-run] [--json] [--scrub TERM]` commits
+  `.shapa/` on the default branch only. It never pushes, touches only
+  wiki paths, and leaves other staged work alone. `install.sh` wires it
+  to the Claude Code `SessionEnd` hook, plus a `SessionStart` catch-up
+  for anything left uncommitted from a prior session. `install.sh
+  --no-auto-commit` opts out. An optional `scrub_terms` list in
+  `~/.shapa/config.json` redacts matching terms before a commit.
+- Trusted publishing to PyPI: tagging a release (`vX.Y.Z`) and publishing
+  it on GitHub builds the sdist and wheel and uploads them with no
+  stored token.
+- A real README: install paths, a 60-second quickstart, how shapa works,
+  a harness support matrix, and a comparison against other agent memory
+  tools.
+- `CONTRIBUTING.md`, `SECURITY.md`, issue templates and a pull request
+  template.
+
+### Changed
+
+- `pyproject.toml` metadata (description, keywords, classifiers, project
+  URLs) now describes what shapa does today, not the pre-format-4 tool.
+- A bare `shapa init` no longer creates a visible `shapa/` in the current
+  directory; an existing `shapa/` wiki at the top level is still used.
+
+### Fixed
+
+- `shapa ledger git-hooks` wrote its hooks into whatever `core.hooksPath`
+  pointed at, including a machine-wide hooks directory shared by every
+  repo. It now writes only inside the repo's own git directory.
+- `shapa doctor` reported "problems: none" with no global wiki and no
+  harness connected.
+- The default branch is detected from branches that exist in the repo, so
+  a machine-wide `init.defaultBranch` naming another branch no longer
+  blocks the database on the real default branch.
+
+## [0.8.0] - 2026-10-06
+
+### Added
+
+- Wiki format 4: one SQLite database per wiki (`shapa.db`), replacing the
+  format-3 Markdown log. It holds the work ledger (features, jobs,
+  tasks) and memory, rule and issue rows; a derived, gitignored
+  `.shapa-index.db` carries the search index and vectors.
+- The work ledger: `F` features (a branch and a PR), `J` jobs (one
+  commit whose subject starts `J<n>:`), and `T` tasks. `shapa ledger`
+  adds, claims, closes and shows a tree of ledger items.
+- Git hooks for the ledger: a `pre-commit` hook refuses to commit
+  `shapa.db` outside the default branch, and a `post-commit` hook closes
+  the job a commit's subject names.
+- A sweep after every merged feature deletes closed, expired, duplicate,
+  superseded and stale rows; the database's git history keeps the record.
+- Correction capture now stores only the operator's own words as issue
+  rows, never a harness's restatement of them.
+- A resumable `shapa upgrade` path from format 3 to format 4.
+
+Related research and design notes live under `.shapa/arch/` and
+`.shapa/research/` in this repository's own wiki.

shapa-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roukh
+
+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.

shapa-0.9.0/MANIFEST.in

@@ -0,0 +1,18 @@
+# What ships in the sdist, on top of the `shapa` package itself (see
+# [tool.setuptools.package-data] in pyproject.toml for what ships inside
+# the package). Without this file, setuptools' default sdist file list
+# picks up stray top-level `test*.py` files by name pattern - this repo's
+# `tests/` directory needs its `conftest.py` and `fixtures/` to run at all,
+# so a partial copy is worse than none; `prune` drops the whole directory.
+include LICENSE
+include README.md
+include CHANGELOG.md
+include AGENTS.md
+
+prune tests
+prune .shapa
+prune .worktrees
+prune .github
+
+global-exclude __pycache__
+global-exclude *.py[cod]

shapa-0.9.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: shapa
+Version: 0.9.0
+Summary: Memory and a work ledger for coding agents, in one SQLite file per wiki, with harness hooks for Claude Code, Codex and OpenCode.
+Author: Roukh
+License: MIT
+Project-URL: Homepage, https://github.com/Roukh/shapa-llm
+Project-URL: Repository, https://github.com/Roukh/shapa-llm
+Project-URL: Issues, https://github.com/Roukh/shapa-llm/issues
+Project-URL: Changelog, https://github.com/Roukh/shapa-llm/blob/main/CHANGELOG.md
+Keywords: llm,agent,memory,coding-agent,work-ledger,sqlite,claude-code,codex,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: semantic
+Requires-Dist: model2vec>=0.3.0; extra == "semantic"
+Provides-Extra: embeddings
+Requires-Dist: model2vec>=0.3.0; extra == "embeddings"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Dynamic: license-file
+
+# shapa
+
+[![tests](https://github.com/Roukh/shapa-llm/actions/workflows/test.yml/badge.svg)](https://github.com/Roukh/shapa-llm/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/shapa.svg)](https://pypi.org/project/shapa/)
+[![Python versions](https://img.shields.io/pypi/pyversions/shapa.svg)](https://pypi.org/project/shapa/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+shapa gives a coding agent memory and a work ledger that live in one SQLite
+file per project, checked into git, with hooks for Claude Code, Codex and
+OpenCode.
+
+## Install
+
+Once shapa is on PyPI:
+
+```bash
+uv tool install 'shapa[semantic,mcp]'
+# or
+pipx install shapa
+```
+
+Until then, install straight from GitHub:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Roukh/shapa-llm/main/bootstrap.sh | sh
+```
+
+`bootstrap.sh` installs the `shapa` command (pipx, then uv, then `pip
+--user`) and wires Claude Code's hooks. Pass `--with-semantic`, `--with-mcp`
+or `--full` to add the optional extras up front; see the comments at the top
+of the script for every flag and environment variable.
+
+## 60-second quickstart
+
+```bash
+# 1. Install shapa (see above).
+
+# 2. In a git repo, create its wiki:
+cd your-project
+shapa init
+
+# 3. Check that everything is wired correctly:
+shapa doctor
+
+# 4. Start your agent as usual. In Claude Code, shapa's hooks load memory
+#    at session start and on every prompt; Codex and OpenCode reach the
+#    same memory through shapa's MCP tools.
+```
+
+`shapa init` finds the git top level, creates `.shapa/` there and nothing
+else, and installs two git hooks: `pre-commit` keeps the database off
+feature branches, and `post-commit` closes the job a `J<n>:` commit names.
+It never writes into a machine-wide `core.hooksPath` or into hooks owned by
+husky, lefthook or the pre-commit framework; it prints the lines to add
+there instead.
+
+## What it does
+
+- Surfaces relevant memory at session start and injects more on every
+  prompt, ranked by relevance.
+- Turns an operator's correction ("no", "wrong", "not like this") into an
+  attributed issue row, not a buried chat line.
+- Tracks work as a three-level ledger: a feature (`F`, a new capability
+  with its own branch and PR) holds jobs (`J`, one commit each), and a job
+  holds tasks (`T`). Fixes, docs and release work are standalone jobs that
+  share one batch branch and PR per session. A commit whose subject starts
+  `J<n>:` closes that job automatically.
+- Sweeps the database after every merged feature: closed, expired,
+  duplicate, superseded and stale rows are deleted, and the database's git
+  history keeps the record.
+- Commits `.shapa/` on the default branch at the end of each Claude Code
+  session (`shapa commit`), so a clone of the repo carries its memory. It
+  commits only wiki paths and never pushes.
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph Harness
+        H["Claude Code / Codex / OpenCode\n(hooks or MCP)"]
+    end
+    H --> CLI["shapa CLI"]
+    CLI --> DB[("shapa.db\ntracked in git")]
+    CLI --> IDX[(".shapa-index.db\ngitignored, derived")]
+    DB -.rebuilds.-> IDX
+    CLI --> GW["global wiki\n~/.shapa/memory"]
+    CLI --> RW["repo wiki\n.shapa/"]
+```
+
+A repo's wiki is `.shapa/` at its git top level; the global wiki defaults to
+`~/.shapa/memory`. Each holds `shapa.db`: the work ledger plus memory, rule
+and issue rows. A second file, `.shapa-index.db`, holds the search index and
+vectors; it is derived from `shapa.db`, gitignored, and rebuilt on demand. A
+session reads from the global wiki and the current repo's wiki together, and
+writes are scoped to one or the other.
+
+## Harness support
+
+| Harness | Hooks | MCP |
+|---|---|---|
+| Claude Code | yes | yes |
+| Codex | no | yes |
+| OpenCode | no | yes |
+| anything else that speaks MCP | no | by hand (see `shapa mcp`) |
+
+Hooked harnesses get memory pushed to them automatically; any MCP client can
+pull the same `search`, `get` and `save` tools by registering `shapa mcp` as
+a stdio server itself.
+
+## How it compares
+
+Figures below are each project's own numbers, checked in October 2026; they
+move fast and several benchmark claims in this space are disputed.
+
+| Tool | Storage | Git-tracked | Work ledger | License |
+|---|---|---|---|---|
+| **shapa** | one SQLite file per wiki | yes, on the default branch | yes (F/J/T) | MIT |
+| claude-mem | SQLite plus Chroma | no | no | Apache-2.0 |
+| mem0 + OpenMemory MCP | vector DB plus graph | no | no | Apache-2.0 |
+| basic-memory | Markdown plus wikilinks, Obsidian sync | if you commit the files | no | AGPL-3.0 |
+| beads | Dolt, JSONL export | yes | yes (dependency graph, not memory) | MIT |
+| native harness memory (Claude Code, Codex, Cursor, ...) | machine-local files | no | no | - |
+
+None of the native, per-harness memory features are git-tracked, shared
+across harnesses, split into a global and a repo tier, or tied to a work
+ledger. The trade-off: a SQLite file does not diff or merge like Markdown,
+which is why shapa commits it only on the default branch.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `shapa init [DIR] [--no-git] [--obsidian] [--global]` | create and register a wiki, with git hooks in a repo |
+| `shapa doctor` | check the whole install; exits 1 with a fix command per problem |
+| `shapa status` | the same report as `doctor`, without the exit code |
+| `shapa commit [--hook] [--dry-run] [--json] [--scrub TERM]` | commit `.shapa/` on the default branch |
+| `shapa bootstrap` | session-start overview of every wiki in scope |
+| `shapa fetch` | rank and surface memory relevant to a prompt |
+| `shapa get ID` | print a row's or a note's full text |
+| `shapa save` | write one note or row (`--scope global\|repo\|external`) |
+| `shapa row add\|edit\|rm\|link\|tag\|list` | manage memory, rule and issue rows |
+| `shapa ledger add\|claim\|close\|tree\|issues` | manage the work ledger |
+| `shapa correction` | record an operator correction as an issue row |
+| `shapa maintain [--prune] [--dry-run]` | self-heal: merge duplicates, prune stale and orphaned rows |
+| `shapa validate` | check note and wiki frontmatter |
+| `shapa upgrade [--all] [--check]` | bring a wiki to the current format |
+| `shapa mcp` | run the MCP stdio server (`search`, `get`, `save`, `placement`) |
+| `shapa serve` | run the optional warm per-wiki daemon |
+
+Run `shapa` with no arguments for the full, versioned usage text.
+
+## Files and privacy
+
+Everything shapa reads or writes stays on disk, in files you own:
+
+- `~/.shapa/config.json` and `~/.shapa/wikis.json`: the global wiki pointer
+  and the registry of known wikis.
+- `~/.shapa/memory/`: the global wiki, unless `shapa init --global DIR`
+  put it elsewhere.
+- `<repo>/.shapa/shapa.db`: that repo's wiki, tracked in git.
+- `<repo>/.shapa/.shapa-index.db`: the derived search index, gitignored.
+
+There is no hosted service and no account, and shapa makes no network calls
+of its own. Two exceptions you opt into: the `[semantic]` extra downloads
+its embedding model once, and session distillation
+(`SHAPA_CAPTURE_DISTILL=1`) and `shapa maintain --resolve` run the `claude`
+CLI you already use. The core engine has no dependencies beyond the Python
+standard library.
+
+## Configuration
+
+- `$SHAPA_MEMORY` overrides the resolved wiki directory for one process.
+- `[semantic]` extra (`model2vec`) turns on local embeddings for fetch and
+  maintain; without it, shapa uses BM25 and token overlap.
+- `[mcp]` extra (`mcp`) upgrades `shapa mcp` to the reference MCP SDK; it
+  works without the extra too, through a standard-library JSON-RPC shim.
+- `scrub_terms` in `~/.shapa/config.json`: an optional list of terms
+  `shapa commit` redacts before committing `.shapa/`.
+- `install.sh --no-auto-commit` skips wiring `shapa commit` into Claude
+  Code's session hooks; run `shapa commit` yourself instead.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, the test matrix
+and the house rules this project runs on.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

shapa-0.9.0/README.md

@@ -0,0 +1,189 @@
+# shapa
+
+[![tests](https://github.com/Roukh/shapa-llm/actions/workflows/test.yml/badge.svg)](https://github.com/Roukh/shapa-llm/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/shapa.svg)](https://pypi.org/project/shapa/)
+[![Python versions](https://img.shields.io/pypi/pyversions/shapa.svg)](https://pypi.org/project/shapa/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+shapa gives a coding agent memory and a work ledger that live in one SQLite
+file per project, checked into git, with hooks for Claude Code, Codex and
+OpenCode.
+
+## Install
+
+Once shapa is on PyPI:
+
+```bash
+uv tool install 'shapa[semantic,mcp]'
+# or
+pipx install shapa
+```
+
+Until then, install straight from GitHub:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Roukh/shapa-llm/main/bootstrap.sh | sh
+```
+
+`bootstrap.sh` installs the `shapa` command (pipx, then uv, then `pip
+--user`) and wires Claude Code's hooks. Pass `--with-semantic`, `--with-mcp`
+or `--full` to add the optional extras up front; see the comments at the top
+of the script for every flag and environment variable.
+
+## 60-second quickstart
+
+```bash
+# 1. Install shapa (see above).
+
+# 2. In a git repo, create its wiki:
+cd your-project
+shapa init
+
+# 3. Check that everything is wired correctly:
+shapa doctor
+
+# 4. Start your agent as usual. In Claude Code, shapa's hooks load memory
+#    at session start and on every prompt; Codex and OpenCode reach the
+#    same memory through shapa's MCP tools.
+```
+
+`shapa init` finds the git top level, creates `.shapa/` there and nothing
+else, and installs two git hooks: `pre-commit` keeps the database off
+feature branches, and `post-commit` closes the job a `J<n>:` commit names.
+It never writes into a machine-wide `core.hooksPath` or into hooks owned by
+husky, lefthook or the pre-commit framework; it prints the lines to add
+there instead.
+
+## What it does
+
+- Surfaces relevant memory at session start and injects more on every
+  prompt, ranked by relevance.
+- Turns an operator's correction ("no", "wrong", "not like this") into an
+  attributed issue row, not a buried chat line.
+- Tracks work as a three-level ledger: a feature (`F`, a new capability
+  with its own branch and PR) holds jobs (`J`, one commit each), and a job
+  holds tasks (`T`). Fixes, docs and release work are standalone jobs that
+  share one batch branch and PR per session. A commit whose subject starts
+  `J<n>:` closes that job automatically.
+- Sweeps the database after every merged feature: closed, expired,
+  duplicate, superseded and stale rows are deleted, and the database's git
+  history keeps the record.
+- Commits `.shapa/` on the default branch at the end of each Claude Code
+  session (`shapa commit`), so a clone of the repo carries its memory. It
+  commits only wiki paths and never pushes.
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph Harness
+        H["Claude Code / Codex / OpenCode\n(hooks or MCP)"]
+    end
+    H --> CLI["shapa CLI"]
+    CLI --> DB[("shapa.db\ntracked in git")]
+    CLI --> IDX[(".shapa-index.db\ngitignored, derived")]
+    DB -.rebuilds.-> IDX
+    CLI --> GW["global wiki\n~/.shapa/memory"]
+    CLI --> RW["repo wiki\n.shapa/"]
+```
+
+A repo's wiki is `.shapa/` at its git top level; the global wiki defaults to
+`~/.shapa/memory`. Each holds `shapa.db`: the work ledger plus memory, rule
+and issue rows. A second file, `.shapa-index.db`, holds the search index and
+vectors; it is derived from `shapa.db`, gitignored, and rebuilt on demand. A
+session reads from the global wiki and the current repo's wiki together, and
+writes are scoped to one or the other.
+
+## Harness support
+
+| Harness | Hooks | MCP |
+|---|---|---|
+| Claude Code | yes | yes |
+| Codex | no | yes |
+| OpenCode | no | yes |
+| anything else that speaks MCP | no | by hand (see `shapa mcp`) |
+
+Hooked harnesses get memory pushed to them automatically; any MCP client can
+pull the same `search`, `get` and `save` tools by registering `shapa mcp` as
+a stdio server itself.
+
+## How it compares
+
+Figures below are each project's own numbers, checked in October 2026; they
+move fast and several benchmark claims in this space are disputed.
+
+| Tool | Storage | Git-tracked | Work ledger | License |
+|---|---|---|---|---|
+| **shapa** | one SQLite file per wiki | yes, on the default branch | yes (F/J/T) | MIT |
+| claude-mem | SQLite plus Chroma | no | no | Apache-2.0 |
+| mem0 + OpenMemory MCP | vector DB plus graph | no | no | Apache-2.0 |
+| basic-memory | Markdown plus wikilinks, Obsidian sync | if you commit the files | no | AGPL-3.0 |
+| beads | Dolt, JSONL export | yes | yes (dependency graph, not memory) | MIT |
+| native harness memory (Claude Code, Codex, Cursor, ...) | machine-local files | no | no | - |
+
+None of the native, per-harness memory features are git-tracked, shared
+across harnesses, split into a global and a repo tier, or tied to a work
+ledger. The trade-off: a SQLite file does not diff or merge like Markdown,
+which is why shapa commits it only on the default branch.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `shapa init [DIR] [--no-git] [--obsidian] [--global]` | create and register a wiki, with git hooks in a repo |
+| `shapa doctor` | check the whole install; exits 1 with a fix command per problem |
+| `shapa status` | the same report as `doctor`, without the exit code |
+| `shapa commit [--hook] [--dry-run] [--json] [--scrub TERM]` | commit `.shapa/` on the default branch |
+| `shapa bootstrap` | session-start overview of every wiki in scope |
+| `shapa fetch` | rank and surface memory relevant to a prompt |
+| `shapa get ID` | print a row's or a note's full text |
+| `shapa save` | write one note or row (`--scope global\|repo\|external`) |
+| `shapa row add\|edit\|rm\|link\|tag\|list` | manage memory, rule and issue rows |
+| `shapa ledger add\|claim\|close\|tree\|issues` | manage the work ledger |
+| `shapa correction` | record an operator correction as an issue row |
+| `shapa maintain [--prune] [--dry-run]` | self-heal: merge duplicates, prune stale and orphaned rows |
+| `shapa validate` | check note and wiki frontmatter |
+| `shapa upgrade [--all] [--check]` | bring a wiki to the current format |
+| `shapa mcp` | run the MCP stdio server (`search`, `get`, `save`, `placement`) |
+| `shapa serve` | run the optional warm per-wiki daemon |
+
+Run `shapa` with no arguments for the full, versioned usage text.
+
+## Files and privacy
+
+Everything shapa reads or writes stays on disk, in files you own:
+
+- `~/.shapa/config.json` and `~/.shapa/wikis.json`: the global wiki pointer
+  and the registry of known wikis.
+- `~/.shapa/memory/`: the global wiki, unless `shapa init --global DIR`
+  put it elsewhere.
+- `<repo>/.shapa/shapa.db`: that repo's wiki, tracked in git.
+- `<repo>/.shapa/.shapa-index.db`: the derived search index, gitignored.
+
+There is no hosted service and no account, and shapa makes no network calls
+of its own. Two exceptions you opt into: the `[semantic]` extra downloads
+its embedding model once, and session distillation
+(`SHAPA_CAPTURE_DISTILL=1`) and `shapa maintain --resolve` run the `claude`
+CLI you already use. The core engine has no dependencies beyond the Python
+standard library.
+
+## Configuration
+
+- `$SHAPA_MEMORY` overrides the resolved wiki directory for one process.
+- `[semantic]` extra (`model2vec`) turns on local embeddings for fetch and
+  maintain; without it, shapa uses BM25 and token overlap.
+- `[mcp]` extra (`mcp`) upgrades `shapa mcp` to the reference MCP SDK; it
+  works without the extra too, through a standard-library JSON-RPC shim.
+- `scrub_terms` in `~/.shapa/config.json`: an optional list of terms
+  `shapa commit` redacts before committing `.shapa/`.
+- `install.sh --no-auto-commit` skips wiring `shapa commit` into Claude
+  Code's session hooks; run `shapa commit` yourself instead.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, the test matrix
+and the house rules this project runs on.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

shapa-0.9.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shapa"
+version = "0.9.0"
+description = "Memory and a work ledger for coding agents, in one SQLite file per wiki, with harness hooks for Claude Code, Codex and OpenCode."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Roukh" }]
+keywords = [
+    "llm",
+    "agent",
+    "memory",
+    "coding-agent",
+    "work-ledger",
+    "sqlite",
+    "claude-code",
+    "codex",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+]
+dependencies = []  # core engine is pure standard library
+
+[project.optional-dependencies]
+# Activates local semantic embeddings for fetch + maintain (else BM25/Jaccard).
+# `semantic` is the current name (shapa-backend-spec.md §3); `embeddings` is
+# kept as a deprecated alias with identical deps for one release. model2vec
+# (potion-base-8M) replaces sentence-transformers as of Slice 6: numpy-only,
+# no torch, ~94.7% of MiniLM's MTEB at a fraction of the install/latency cost.
+semantic = ["model2vec>=0.3.0"]
+embeddings = ["model2vec>=0.3.0"]
+# The MCP stdio server (shapa/mcp.py, shapa-backend-spec.md §7.1, Slice 6).
+# The official SDK is optional even with this extra installed: shapa/mcp.py
+# falls back to a stdlib-only JSON-RPC shim (the same wire protocol a real
+# MCP client speaks over stdio) whenever it is absent, so `shapa mcp` always
+# works, extra or not - this just upgrades it to the reference SDK surface.
+mcp = ["mcp>=1.0.0"]
+
+[project.scripts]
+shapa = "shapa.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Roukh/shapa-llm"
+Repository = "https://github.com/Roukh/shapa-llm"
+Issues = "https://github.com/Roukh/shapa-llm/issues"
+Changelog = "https://github.com/Roukh/shapa-llm/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+packages = ["shapa"]
+
+[tool.setuptools.package-data]
+# Design docs (arch/ + AGENTS.md) shipped with the tool and installed into a
+# wiki by `shapa init`.
+shapa = ["assets/*.md", "assets/arch/*.md", "assets/skills/*/SKILL.md", "assets/prompts/*.md"]

shapa-0.9.0/setup.cfg

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