slopie 0.0.0-stage → 1.6.2

package/LICENSE

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

package/NOTICE

@@ -0,0 +1,75 @@
+potsherd
+Copyright (c) 2026 potsherd contributors
+
+This product includes software developed as part of:
+
+  episodic-memory — https://github.com/obra/episodic-memory
+  Copyright (c) 2025 Jesse Vincent
+  Licensed under the MIT License.
+
+  gitleaks — https://github.com/gitleaks/gitleaks
+  Copyright (c) 2019 Zachary Rice
+  Licensed under the MIT License.
+
+  secretlint — https://github.com/secretlint/secretlint
+  Copyright (c) 2020 Secretlint
+  Licensed under the MIT License.
+
+potsherd's engine (`packages/core`) is a hard fork of episodic-memory. The
+upstream revision the fork was taken from is:
+
+  upstream: obra/episodic-memory
+  tag:      v1.4.2
+  commit:   10757690210574421f1df5f35835af8d0c74d984
+  date:     2026-05-21
+
+That revision is reachable from this repository as the fetch-only git remote
+`upstream-episodic`, so `git log upstream-episodic/main` and
+`git diff 1075769..upstream-episodic/main -- src/` keep working:
+
+  git remote add upstream-episodic https://github.com/obra/episodic-memory.git
+  git fetch upstream-episodic --no-tags \
+    'refs/heads/main:refs/remotes/upstream-episodic/main'
+
+No upstream commit is merged into this history. Files were hand-ported into
+potsherd's layer layout and each one carries a provenance header naming the
+upstream path and revision. `docs/upstream/PORT-LOG.md` lists every upstream
+source file and records whether it was taken verbatim, adapted, or refused,
+and why.
+
+The secret-detection rule pack in `packages/core/src/redact-rules.ts` (L2,
+`plans/03-ARCHITECTURE.md` §5) is ported from gitleaks' `config/gitleaks.toml`
+and from secretlint's `@secretlint/secretlint-rule-preset-recommend`. Neither
+project's runtime is a dependency: the patterns were transcribed and each rule
+records its upstream rule id in its `source` field. No rule in that file was
+written from memory.
+
+Generic fixes made here are prepared as upstream pull requests under
+`docs/upstream/` and are not submitted by any agent.
+
+Third-party dependencies retain their own licenses; see the `licenses`
+section of each package's `package.json` and `node_modules`.
+
+History rewrite, 22 August 2026
+-------------------------------
+`docs/upstream/PHASE-1-SCOUT.md` published real transcript prose — an assistant
+`thinking` block and a truncated `<user_query>`, both from one machine's private
+sessions — from phase 1 until 22 August 2026. The samples are synthetic now, and
+that path was removed from every commit with `git filter-repo` and force-pushed,
+so the leaked blob is not reachable from any commit on `origin/main`.
+
+The root commit after the rewrite is `6697ca9`, and the `v1.0.0` tag now points at
+`548b5b5`, whose tree no longer contains the file.
+**A clone taken before 22 August 2026 still holds the original blob.** Re-clone
+rather than pull if you have one.
+
+Bundled transport accounting tokenizer
+-------------------------------------
+js-tiktoken 1.0.21 and cl100k-base ranks, MIT License.
+Copyright (c) 2022 OpenAI, Shantanu Jain.
+Full notice: licenses/js-tiktoken-MIT.txt.
+This tokenizer is a transport accounting unit, not the host model tokenizer.
+
+Models.dev
+----------
+The terminal audit includes reduced public model/pricing metadata from Models.dev (Anomaly). Source: https://github.com/anomalyco/models.dev. Licensed under MIT; see licenses/models-dev-MIT.txt. Snapshot retrieval date and hash are retained in each audit price basis.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# Slopie
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Slopie](https://github.com/HulkInTherapy/slopie), formerly Potsherd, is local memory for coding-agent sessions. Capture supported history, find exact source evidence, and save scoped handoffs with provenance.
+
+**Slopie 1.6.1 is published with provenance; this checkout prepares the 1.6.2 live-store patch.** Requires Node.js 22 or newer.
+
+## Audit your recorded history
+
+```sh
+npx slopie audit
+```
+
+The default interactive audit sends selected redacted conversation text to OpenCode Zen and TypeSafe/Jev after its opening recipient notice, with no extra Enter step. It presents recorded API-equivalent value at a dated current price catalog, favourite model, real projects, recent Jev work stories, memorable source lines and direct-user language. Arrow keys or Tab switch sections; Enter opens details and evidence, Esc returns, S freezes the current view and q exits. `--tone elegant|witty|chaotic|roast` overrides the inferred voice. `--plain`, `--ascii`, `--no-color` and `--no-motion` support simpler terminals.
+
+Jev analyzes the largest complete recent scope that fits the free token and estimated time allowance: All, 45, 30, 7 or 3 days. When none fits, an explicitly labelled selection of the newest coherent episodes keeps the scope bounded and the calendar coverage partial. Its opening notice names OpenCode Zen and TypeSafe/Jev as recipients. Retained archives remain read-only; redacted conversation text is sent only through the qualified free route, with no paid fallback. The anonymous free-model route previously returned zero-cost answers for an authored synthetic sample. Current free capacity is limited: four authorized private requests received quota errors and no accepted answers, so private semantic accuracy is unavailable. No private accuracy pass or guaranteed capacity is claimed. Results and date inventories use a separate body-free local cache. Prices revalue recorded tokens at current catalog rates; they are not historical invoices. Missing usage, endpoints, rates or provenance stay visible.
+
+The audit remains experimental. The unchanged large synthetic fixture took about 33 seconds cold and 22 seconds warm. Independent, untuned scores were usefulness 7/10, ease 8/10 and appearance 8/10 at 80 columns (7/10 at 40); these do not establish broader semantic accuracy.
+
+Use `slopie audit --legacy` for the local retention audit, or set `POTSHERD_OFFLINE=1` to keep the new retrospective local. Window estimates describe remaining analysis after inventory, not the entire cold command; large cold archives can take longer. `--sweep` and `--verify` keep their prior behavior. See [terminal audit coverage and privacy](https://github.com/HulkInTherapy/slopie/blob/main/docs/audit-terminal.md).
+
+## Install and use
+
+Install with `npm install -g slopie` and run `slopie audit`. The `potsherd` executable remains a compatibility alias. To build this checkout from source:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+pnpm vendor
+node packages/cli/bin/slopie.js --help
+```
+
+Use an owned test store and explicit source roots to try capture and search:
+
+```sh
+node packages/cli/bin/slopie.js maintain --migrate --potsherd-dir /path/to/test-store
+node packages/cli/bin/slopie.js index --enroll codex,claude --codex-dir /path/to/codex --claude-dir /path/to/claude --potsherd-dir /path/to/test-store
+node packages/cli/bin/slopie.js find "latest project decisions" --project /example/project --potsherd-dir /path/to/test-store --json
+```
+
+`--enroll` enables automatic capture for those source roots. Semantic model assets require explicit `maintain --acquire-assets --rebuild`; missing assets produce labelled degraded coverage.
+
+## Integrations and support
+
+The v2 agent contract exposes four tools: `potsherd_recall` for scoped recall, `potsherd_read` for exact source evidence, `potsherd_graft` for deterministic handoffs, and `potsherd_write` for explicit authored memory. The [Codex plugin](https://github.com/HulkInTherapy/slopie/blob/main/plugins/codex/README.md), [Claude Code plugin](https://github.com/HulkInTherapy/slopie/blob/main/plugins/claude-code/README.md), native pi extension, and OpenCode MCP configuration use this contract. See [installation and MCP configuration](https://github.com/HulkInTherapy/slopie/blob/main/docs/mcp-clients.md), the [agent contract](https://github.com/HulkInTherapy/slopie/blob/main/docs/AGENT-CONTRACT.md), and the [reader contract](https://github.com/HulkInTherapy/slopie/blob/main/docs/reader-contract.md).
+
+Existing `POTSHERD_*` settings, `--potsherd-dir`, local data/cache paths, plugin identities and tool IDs retain their compatibility names.
+
+Host verification differs by integration. [Historical memory release notes](https://github.com/HulkInTherapy/slopie/blob/main/docs/release-candidate.md) describe measured results and remaining limits; [release history](https://github.com/HulkInTherapy/slopie/blob/main/CHANGELOG.md) tracks product versions. This release is not certified as unattended primary memory.
+
+## Evidence and upgrades
+
+Only explicit write creates authored memory. Relevance scores and source links do not prove a claim; verify exact evidence and distinguish human decisions from assistant recaps, tool observations, and historical instructions. Reader validation checks structure and citation membership, not semantic entailment. Partial capture cannot establish global absence.
+
+Before upgrading, back up the store and retain the previous package. `maintain --migrate` creates a pre-upgrade backup. To roll back, stop owned host/MCP processes, preserve the upgraded store, restore a copy of the backup, and run the previous package against that copy.
+
+MIT licensed. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/bin/potsherd.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The published entry point. `dist/potsherd.js` is a single bundled file so
+// that `npx potsherd audit` needs no workspace resolution and no build step.
+import('../dist/potsherd.js').catch((err) => {
+  console.error('potsherd failed to start:', err?.message ?? err);
+  // NOT `npm i -g potsherd`: the package is unpublished, so that is a 404
+  // and telling somebody whose install is already broken to run it twice is
+  // the worst kind of fix line. Phase 7 publishes; until then this is it.
+  console.error('this usually means the package did not build. try: pnpm install && pnpm build');
+  process.exit(1);
+});

package/bin/slopie.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Public Slopie launcher; storage and the potsherd launcher remain compatible.
+process.env['POTSHERD_CLI_PUBLIC_NAME']='slopie';
+import('../dist/potsherd.js').catch((err)=>{
+ console.error('slopie failed to start:',err?.message??err);
+ console.error('this usually means the package did not build. try: pnpm install && pnpm build');
+ process.exit(1);
+});