outrage 0.1.0__tar.gz

outrage-0.1.0/.claude/RESUME.md

@@ -0,0 +1,23 @@
+# Claude Code — resume checkpoint
+
+Session: 440063bd-742b-41f8-8b80-0b5fe1852641
+Written: 2026-08-21T11:20:15.294Z
+Trigger: near-limit
+Ref with your in-progress files: refs/claude/checkpoint-440063bd
+
+## To resume
+
+    claude --resume 440063bd-742b-41f8-8b80-0b5fe1852641
+
+(or open Claude Code in this directory and run /resume)
+
+## Plan (from TodoWrite state)
+
+No task list was active; see transcript via the resume command above.
+
+---
+
+Don't want these changes? Resume this session (above), then run
+`/rewind` to roll back the turn's tool edits (bash-made changes
+excluded). refs/claude/checkpoint-440063bd holds a full snapshot until this session's
+next checkpoint, or for up to ~2 weeks.

outrage-0.1.0/.claude/agents/rage-annotate.md

@@ -0,0 +1 @@
+../../src/outrage/agents/rage-annotate.md

outrage-0.1.0/.claude/agents/rage-backfill.md

@@ -0,0 +1 @@
+../../src/outrage/agents/rage-backfill.md

outrage-0.1.0/.claude/agents/rage-search.md

@@ -0,0 +1 @@
+../../src/outrage/agents/rage-search.md

outrage-0.1.0/.claude/skills/rage/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: rage
+description: Keep and recover working knowledge in this project's rage document store - notes, decisions, findings and task state that outlive one session. Use when starting or resuming work and the question is what earlier sessions established ("where were we", "what do we already know about X", "continue", "pick up where we left off"); when something worth keeping has just been settled (a decision and its reasoning, a finding that took effort to get, where the work got to); when asked to remember, store or save context; and before a session ends or its context is compacted.
+---
+
+# The rage store
+
+A document store for this project, reached through the `rage` MCP tools. The
+tools carry the key grammar and the argument rules; this skill covers when to
+use them and what to name things.
+
+## Start at `readme`
+
+Every store's entry point is the document at `readme`: what this particular
+store holds, and what to read before anything else. The server carries it at
+the top of its instructions, so it arrives without being asked for and there is
+normally nothing to do here. If it did not arrive, read it.
+
+Three things follow from that. A readme long enough to be worth summarising is
+too long - it routes, and the documents it points at explain. It has a hard cap
+of a few hundred characters, because a client cuts the instructions at a length
+it does not announce and the readme is what has to survive that cut; over the
+cap the server reports its length instead of carrying it, which is the signal
+to go and read it. And a store with no readme is asking for one: a session that
+works out how the store is laid out, or what the next session should read
+first, should write that there.
+
+It is read once, when the server starts, so a readme stored now reaches the
+next session rather than this one.
+
+## Survey before reading
+
+One call shows what the store holds:
+
+```
+get_documents(meta_name=["title"])
+```
+
+That returns a title per document, not the documents, so it is cheap enough to
+run at the start of any piece of work. Then read only what looks relevant, with
+`retrieve_document`.
+
+**Read `total`, not just what came back.** The result is a page: `returned`
+titles out of `total` documents, with `next_cursor` set when there are more.
+Twenty of twenty-two is a listing and you have seen the store; twenty of four
+thousand is a sample, and treating it as the store is how a session concludes
+confidently from a fraction of it. To continue, pass `next_cursor` back as
+`after`. To look at one part instead of everything, pass `key`.
+
+Check `without_meta` too. It reports how many documents carry no title, with a
+few of their keys - the ones the survey cannot show at all, since it can only
+report documents that have one. A survey that omits them silently is a survey
+you cannot trust. It is always present, and it covers exactly the stretch of
+the store this page covers, so paging the survey walks the gaps alongside the
+titles instead of repeating a subtree-wide total on every page.
+
+It is a count, not a listing, and carries no cursor: `keys_missing_meta` is
+what enumerates them, and `rage-backfill` fills them in.
+
+## Key conventions
+
+Three top level namespaces. Nothing enforces them; they exist so that a later
+session can guess where to look.
+
+`context/<n>/…` - one numbered thread of work. Do not invent the number: store
+at `context/?/task` first and the result reports the key it allocated, then put
+everything else in that thread alongside it.
+
+* `context/<n>/task` - what is being attempted, in a few lines.
+* `context/<n>/state` - where it got to, what is unfinished, what to do next.
+* `context/<n>/design`, `…/findings`, `…/decisions` - whatever the work
+  produced that is worth keeping.
+
+`project/reference/<topic>` - durable facts about the project itself, belonging
+to no single thread: the environment, conventions, current status. Updated in
+place as they change.
+
+`notes/<path>` - notes about one file, keyed to mirror its path, as in
+`notes/src/outrage/store.py`.
+
+Pass `title` on every document. It is what the survey above can see, and a
+document without one is findable only by someone who already knows its key.
+
+Store a `!summary` as well for any document whose subject its title cannot
+carry. `rage-search` screens on title *then* summary, so a document with a
+title and no summary is judged on the title alone - and "Notes from the Tuesday
+run" is an honest title that tells a reader nothing. Aim for about a fifth of
+the document: a summary that approaches the length of its document costs as much
+to screen as the document costs to read. `rage-backfill` fills these in across a subtree,
+which is the right thing to run after adding several documents at once.
+
+## What is worth storing
+
+Store what cost something to learn and that nothing else in the project
+records:
+
+* a decision, and why the alternative was rejected
+* a finding from actually running the thing - an error, a behaviour, a
+  constraint in a dependency
+* where the work got to, and what the next step is
+* a correction: something believed at the start of the session and found false
+
+Do not store what the repository already holds - what the code does, what the
+diff changed, what the commit messages say. A note restating the code is a note
+that will go stale and then mislead, and it costs a later session the read.
+
+The test is whether someone could act on the document without the session that
+wrote it.
+
+## Store as the work goes, not at the end
+
+Store each thing once it is settled. A session that plans to write everything up
+at the end stores nothing if it is cut short, and a full context window is
+exactly the ending that arrives without warning.
+
+Rewrite the same key rather than accumulating new ones: `context/1/state` should
+be the current state, not the first of several. Storing overwrites, which is
+what makes this cheap.
+
+Keep `project/reference/…` current when the facts under it change. A stale
+reference is worse than an absent one, because it is believed.
+
+## One document, one question
+
+Rewriting a key keeps it current; it is not licence to let it grow. When there
+is more to keep, prefer **adding a document beneath it** to extending the one
+that is there. Sub-documents are the intended shape, and `?` allocates a key at
+any depth - `context/1/findings/?` writes the next document under `findings` -
+so adding one costs no naming decision and no thought about where it goes.
+
+A document should be readable in one call. `retrieve_document` returns 8000
+characters by default, so a longer document is read in slices, and a session
+that judges it from the first slice judges it wrongly and silently.
+
+Size is the symptom; scope is the cause. `project/reference/planned` reached
+11389 characters because it answered five questions at once - what CLI pieces
+remain, what is open on the agents, what the log reader should do, how the
+checkpoint prompt gets delivered, which files are stale. No title and no
+summary can route a reader to the right part of a document like that, so it is
+read whole or not at all.
+
+Split along the questions, not by length. A key can hold content *and* have
+keys beneath it, so the general document stays where it is and the detail goes
+below: `project/reference/planned` is now a short index over `planned/cli`,
+`planned/agents`, `planned/log-reader` and the rest. Anything already pointing
+at the old key still lands somewhere useful, which is what makes a split safe
+to do late - but adding as you go is cheaper than splitting afterwards.
+
+## Before the end
+
+Whether the session is ending, being handed over, or about to be compacted:
+
+* make sure `context/<n>/state` actually describes where things stand
+* store anything settled that is still only in the conversation
+* check the survey - anything under `without_meta` needs a title

outrage-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+.env
+*.sqlite
+*.sqlite3
+*.db
+.outrage/
+.rage/
+.DS_Store
+.claude/settings.local.json
+.claude/harness-canary/
+
+# The SessionStart canary probes the client, not this project: it is
+# registered in the untracked settings.local.json, its log above is ignored,
+# and it ships nowhere. It stays on the machine that runs it.
+.claude/hooks/sessionstart_canary.py
+.claude/hooks/sessionstart-canary.sh
+.claude/settings.json
+.outrage-*/
+.rage-*/
+
+# Sphinx build output
+docs/_build/

outrage-0.1.0/.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "rage": {
+      "command": "/Users/john/miniforge3/envs/rage/bin/outrage-server",
+      "args": [
+        "--dir",
+        "/Users/john/Library/CloudStorage/OneDrive-Personal/Projects/Rage/.outrage",
+        "--mount",
+        "mount_test=mount-test.sqlite",
+        "--mount-ro",
+        "ref=ref.sqlite",
+        "--mount-ro",
+        "pyref=python.parquet",
+        "--log"
+      ]
+    }
+  }
+}

outrage-0.1.0/CLAUDE.md

@@ -0,0 +1,25 @@
+# Outrage
+
+This project keeps its working knowledge - decisions, findings, and where the
+work got to - in its own rage document store, reached through the `rage` MCP
+tools. That store is the record. **This file is only a pointer to it**, so that
+nothing here can go stale against what the store says.
+
+## Start here
+
+Read the document at key `project`. It is an index of what to read and *when it
+applies*, and it routes to everything else. A survey by title
+(`get_documents(meta_name=["title"])`) tells you what documents are about; the
+`project` document tells you which one you need before you know to look.
+
+## Before snapshotting the store
+
+Read `project/reference/snapshots` first. Copying `.outrage/store.sqlite` with `cp`
+succeeds and produces a **silently stale** store, potentially a whole schema
+version behind. Use `outrage backup`.
+
+## Conventions
+
+The `rage` skill (`.claude/skills/rage/SKILL.md`) holds the key conventions and
+what is worth storing. The tools themselves carry the key grammar and the
+argument rules.

outrage-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 John M Reynolds
+
+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.

outrage-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: outrage
+Version: 0.1.0
+Summary: A key-addressed retrieval system for coding agents
+Project-URL: Homepage, https://github.com/ZandevOxford/outrage
+Project-URL: Issues, https://github.com/ZandevOxford/outrage/issues
+Author-email: John M Reynolds <zandev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: sphinx>=8; extra == 'docs'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=18; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# Outrage
+
+A simple retrieval system for coding agents: an MCP server, a data store, and
+skills that let an agent keep notes, designs and task context in a store local
+to the project it is working on.
+
+Retrieval is by key rather than by similarity. Keys are hierarchical, slash
+delimited strings such as `context/<guid>/design`, and any key may carry
+metadata such as `context/<guid>/design/!title`. Since an agent knows the keys it
+wrote, lexical addressing is enough, and the system stays deterministic and free
+of external dependencies. Semantic search is a possible later addition, layered
+on as metadata rather than as a change to the model.
+
+Keys are not paths, but they are shaped like them, so a key can mirror one:
+`notes/src/myfile.py` for notes about a source file. A key being written may
+also use `?` in place of a segment - storing at `tmp/?` writes to `tmp/1`, and
+the store reports the key it chose.
+
+## Purpose
+
+To provide a hierarchical RAG (Retrieval-Augmented Generation) MCP store to use
+with LLM based tools.
+
+## Features
+
+* Simple to get started with - built in initialisation configures everything.
+* Hierarchical store of data and metadata.
+* LLM search - LLM subagents add summary metadata to documents, and LLM subagents can
+  search documents and metadata.
+* Multiple data stores including parquet based stores for large-scale reference material.
+
+## Status
+
+The store, the MCP server, the key handling, the skill and the command line tool
+are implemented. The tool covers the store operations (`outrage get`, `set`,
+`ls`, `dump`, `rm`), bulk export and import to a directory of files (`outrage
+export`, `outrage import`), building a read-only parquet store (`outrage pack`),
+the MCP configuration (`outrage config`), a verified backup (`outrage backup`),
+the event log (`outrage log`), and setting a project up (`outrage init`). See
+[implementation.md](implementation.md) for what is done and what is next.
+
+`outrage init` is the way in: run it in a project and it registers the MCP
+server, installs the `SessionStart` hook, and copies the skill and the agents
+into `.claude/`. It writes only the entries outrage owns, leaves the rest of
+those files alone, and is safe to re-run - which is how a project is repaired
+after an upgrade or after the environment moves. `--dry-run` reports what it
+would change without writing.
+
+## Documentation
+
+* **[design.md](design.md)** - the design. Components, the key namespace and its
+  grammar, tool semantics, and the SQLite schema. Decisions that are deferred or
+  still open are recorded at the end.
+* **[implementation.md](implementation.md)** - what is implemented so far, and
+  the planned build order.
+
+## Components
+
+* **MCP server** - Python, stdio, for local use. Exposes the store as tools.
+* **Data store** - a Python library, independent of MCP so that it can be tested
+  and reused on its own. One interface with two backends behind it, and which
+  one a store uses follows from its file's extension. **SQLite** is the
+  read-write default: a store accumulated a document at a time, which is what
+  session context and notes on a codebase are. **Parquet** is one columnar file,
+  written whole by `outrage pack` and read many times, for a reference base of
+  tens of thousands of documents - 11× smaller than the same corpus in SQLite,
+  and it seeks a range rather than scanning one. It refuses writes, which is the
+  storage rather than a setting.
+* **Skill** - `src/outrage/skills/rage/SKILL.md`, initially for Claude Code,
+  covering when to store and retrieve and what key conventions to follow. It
+  ships inside the package so that an install carries it, and `outrage init`
+  copies it into a project. A `SessionStart` hook in `.claude/settings.json`,
+  installed by the same command, covers the moment a skill would not be reached
+  for on its own.
+* **Event log** - an optional JSON lines record of the requests made and the
+  store accesses beneath them, for answering afterwards what a session actually
+  did. Off unless `outrage config --log` or `outrage-server --log` asks for it.
+* **Backup** - `outrage backup` copies the database through SQLite and checks
+  what it wrote. In the library rather than the tool, because a store in WAL
+  mode keeps recent writes in a sidecar file and copying the `.sqlite` alone
+  yields a near-empty database that still opens cleanly.
+
+## Development
+
+```sh
+conda env create -f environment.yml   # or: conda create -n outrage -c conda-forge python=3.14
+conda activate outrage
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+The stores live in a directory given to the server by `--dir` or `RAGE_DIR`,
+defaulting to `./.outrage/` in the working directory, each as a file inside it:
+`--root-mount FILE` names the one answering for everything (default
+`store.sqlite`) and `--mount KEY=FILE` mounts another under a key. A store file
+is always relative to the directory, so only `--dir` is a path. See
+[design.md](design.md#store-location).
+
+`outrage-server --log` records requests and store accesses as JSON lines, by
+default in `log.jsonl` beside the store. It is off otherwise, since it records
+document text. `--log-content none|excerpt|full` controls how much of that text
+it keeps.
+
+`.mcp.json` registers the server for this project. Its `command` is an absolute
+path into the conda environment, so it is specific to the machine it was written
+on; adjust it after creating the environment elsewhere.

outrage-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Outrage
+
+A simple retrieval system for coding agents: an MCP server, a data store, and
+skills that let an agent keep notes, designs and task context in a store local
+to the project it is working on.
+
+Retrieval is by key rather than by similarity. Keys are hierarchical, slash
+delimited strings such as `context/<guid>/design`, and any key may carry
+metadata such as `context/<guid>/design/!title`. Since an agent knows the keys it
+wrote, lexical addressing is enough, and the system stays deterministic and free
+of external dependencies. Semantic search is a possible later addition, layered
+on as metadata rather than as a change to the model.
+
+Keys are not paths, but they are shaped like them, so a key can mirror one:
+`notes/src/myfile.py` for notes about a source file. A key being written may
+also use `?` in place of a segment - storing at `tmp/?` writes to `tmp/1`, and
+the store reports the key it chose.
+
+## Purpose
+
+To provide a hierarchical RAG (Retrieval-Augmented Generation) MCP store to use
+with LLM based tools.
+
+## Features
+
+* Simple to get started with - built in initialisation configures everything.
+* Hierarchical store of data and metadata.
+* LLM search - LLM subagents add summary metadata to documents, and LLM subagents can
+  search documents and metadata.
+* Multiple data stores including parquet based stores for large-scale reference material.
+
+## Status
+
+The store, the MCP server, the key handling, the skill and the command line tool
+are implemented. The tool covers the store operations (`outrage get`, `set`,
+`ls`, `dump`, `rm`), bulk export and import to a directory of files (`outrage
+export`, `outrage import`), building a read-only parquet store (`outrage pack`),
+the MCP configuration (`outrage config`), a verified backup (`outrage backup`),
+the event log (`outrage log`), and setting a project up (`outrage init`). See
+[implementation.md](implementation.md) for what is done and what is next.
+
+`outrage init` is the way in: run it in a project and it registers the MCP
+server, installs the `SessionStart` hook, and copies the skill and the agents
+into `.claude/`. It writes only the entries outrage owns, leaves the rest of
+those files alone, and is safe to re-run - which is how a project is repaired
+after an upgrade or after the environment moves. `--dry-run` reports what it
+would change without writing.
+
+## Documentation
+
+* **[design.md](design.md)** - the design. Components, the key namespace and its
+  grammar, tool semantics, and the SQLite schema. Decisions that are deferred or
+  still open are recorded at the end.
+* **[implementation.md](implementation.md)** - what is implemented so far, and
+  the planned build order.
+
+## Components
+
+* **MCP server** - Python, stdio, for local use. Exposes the store as tools.
+* **Data store** - a Python library, independent of MCP so that it can be tested
+  and reused on its own. One interface with two backends behind it, and which
+  one a store uses follows from its file's extension. **SQLite** is the
+  read-write default: a store accumulated a document at a time, which is what
+  session context and notes on a codebase are. **Parquet** is one columnar file,
+  written whole by `outrage pack` and read many times, for a reference base of
+  tens of thousands of documents - 11× smaller than the same corpus in SQLite,
+  and it seeks a range rather than scanning one. It refuses writes, which is the
+  storage rather than a setting.
+* **Skill** - `src/outrage/skills/rage/SKILL.md`, initially for Claude Code,
+  covering when to store and retrieve and what key conventions to follow. It
+  ships inside the package so that an install carries it, and `outrage init`
+  copies it into a project. A `SessionStart` hook in `.claude/settings.json`,
+  installed by the same command, covers the moment a skill would not be reached
+  for on its own.
+* **Event log** - an optional JSON lines record of the requests made and the
+  store accesses beneath them, for answering afterwards what a session actually
+  did. Off unless `outrage config --log` or `outrage-server --log` asks for it.
+* **Backup** - `outrage backup` copies the database through SQLite and checks
+  what it wrote. In the library rather than the tool, because a store in WAL
+  mode keeps recent writes in a sidecar file and copying the `.sqlite` alone
+  yields a near-empty database that still opens cleanly.
+
+## Development
+
+```sh
+conda env create -f environment.yml   # or: conda create -n outrage -c conda-forge python=3.14
+conda activate outrage
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+The stores live in a directory given to the server by `--dir` or `RAGE_DIR`,
+defaulting to `./.outrage/` in the working directory, each as a file inside it:
+`--root-mount FILE` names the one answering for everything (default
+`store.sqlite`) and `--mount KEY=FILE` mounts another under a key. A store file
+is always relative to the directory, so only `--dir` is a path. See
+[design.md](design.md#store-location).
+
+`outrage-server --log` records requests and store accesses as JSON lines, by
+default in `log.jsonl` beside the store. It is off otherwise, since it records
+document text. `--log-content none|excerpt|full` controls how much of that text
+it keeps.
+
+`.mcp.json` registers the server for this project. Its `command` is an absolute
+path into the conda environment, so it is specific to the machine it was written
+on; adjust it after creating the environment elsewhere.