Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,11 @@ distill them into progressively more abstract, navigable knowledge — while kee
auditable by humans. Scale is a requirement, not an aspiration: it is meant to still be useful
at a million documents.

> **Pre-release software.** Phases 0–7 are implemented and tested. Release automation, trusted
> publishing, tag protection, and bounded contributor-agreement enforcement are in place; the
> first public tag remains. The fresh-deployment Docker
> Compose skeleton is documented under
> **Pre-release software.** Phases 0–7 are implemented and tested. The public
> [`v0.1.0`](https://github.com/writeitai/remember-stack/releases/tag/v0.1.0) release is available
> from PyPI and GHCR; release automation, trusted publishing, tag protection, and bounded
> contributor-agreement enforcement are in place. The fresh-deployment Docker Compose skeleton
> is documented under
> [Self-host deployment](website/src/app/docs/deployment/page.mdx); it proves PostgreSQL, MinIO,
> API ingestion, and the first two E0 worker stages, not a production rollout. The build follows
> [plan/plans/roadmap.md](plan/plans/roadmap.md).
Expand Down
18 changes: 10 additions & 8 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# Releasing RememberStack

The `Release` workflow publishes one version to PyPI and GHCR, then creates a GitHub release
containing the Python distributions, the same version-pinned `compose.yaml`, and `.env.example`.
It accepts only tags exactly matching `vMAJOR.MINOR.PATCH`.
containing the Python distributions, the same version-pinned `compose.yaml`, and the example
environment as `default.env.example` (GitHub's public asset name for the source
`.env.example`). It accepts only tags exactly matching `vMAJOR.MINOR.PATCH`.

## One-time owner setup

Expand Down Expand Up @@ -71,11 +72,12 @@ PyPI and GHCR do not support an atomic cross-registry transaction. Never reuse a
version after a partial failure: fix the cause, complete the missing publish when safe, or cut the
next patch version.

## First-release GHCR step
## GHCR visibility

The first container package may be private. After the first successful image push, open the
`remember-stack` package settings in GitHub and change its visibility to **public** so anonymous
Compose pulls work. GitHub warns that a public package cannot be made private again.
The `remember-stack` container package was made public after the `v0.1.0` image push, so later
versions in the same package support anonymous Compose pulls without another visibility step. A
new package namespace would default to private and require the same one-time review. GitHub warns
that a public package cannot be made private again.

The image carries standard OCI source labels generated from the repository metadata, which links
the package back to this repository. Docker Hub is intentionally not a second publication target.
Expand All @@ -88,8 +90,8 @@ Run these checks from a clean machine or temporary directory:
uvx --from rememberstack==0.1.0 remember --version
docker pull ghcr.io/writeitai/remember-stack:0.1.0
gh release download v0.1.0 --repo writeitai/remember-stack \
--pattern compose.yaml --pattern .env.example
cp .env.example .env
--pattern compose.yaml --pattern default.env.example
cp default.env.example .env
docker compose --env-file .env up --no-build --pull always --detach --wait
curl --fail http://localhost:8000/healthz
docker compose --env-file .env down --volumes
Expand Down
20 changes: 16 additions & 4 deletions plan/plans/phase-7-scale-ops.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,34 @@ self-host and reference adapters.

**Entry gates:** none. Work-package-local gates remain explicit: #24 was resolved by D74 before
WP-7.5 implementation. WP-7.6 engineering, account-level registry setup, and D77 governance
activation are complete. The first public tag remains the artifact proof.
activation are complete. The public `v0.1.0` tag supplied the artifact proof.
**Exit criteria:** fixed synthetic scale profiles exercise the D23 shapes and portable batching;
a fixture budget parks and later resumes work without loss; telemetry/admin surfaces expose
pipeline and DLQ state; rebuild and forget drills pass; S55 is green across active serving stores
and a restore cannot resurrect a forgotten identity; release artifacts pass their round trips;
the operator-driven portable restore drill is green without a library transport subsystem.

**Exit evidence (2026-07-23):** WP-7.1–WP-7.7 are merged in PRs
[#120](https://github.com/writeitai/remember-stack/pull/120),
[#122](https://github.com/writeitai/remember-stack/pull/122),
[#123](https://github.com/writeitai/remember-stack/pull/123),
[#124](https://github.com/writeitai/remember-stack/pull/124),
[#126](https://github.com/writeitai/remember-stack/pull/126),
[#128](https://github.com/writeitai/remember-stack/pull/128), and
[#131](https://github.com/writeitai/remember-stack/pull/131). The
[`v0.1.0` release run](https://github.com/writeitai/remember-stack/actions/runs/30009101734)
passed its architecture, style, type, full-suite, and build steps plus its PyPI, GHCR, and
GitHub Release jobs;
the published GHCR manifest is anonymously readable.

| WP | Goal | Reads | Depends | Deliverable | Acceptance | Status |
|---|---|---|---|---|---|---|
| WP-7.1 | Backfill lanes + seeding + reprocessing orchestration (version bumps) | orchestration §3–4 | Phase 6 | lane machinery | steady-state unaffected during backfill test | done |
| WP-7.2 | Reproducible scale battery: D23 partitions/indexes, hub entities/lineages, recount cost, and provider-neutral read/write batching | schema §12; D23; lifecycle §11.5; orchestration §5; retrieval §13.7 | WP-7.1 | fixed synthetic profiles + report | shapes and batching invariants recorded; timings remain measurements, not hosted SLAs | done |
| WP-7.3 | Cost metering + configurable budget enforcement | orchestration §4; schema §2 `cost_ledger` | WP-7.1 | enforcement + admin inspection | explicit fixture ceiling parks and resumes an over-budget lane; attribution is visible | done |
| WP-7.4 | Operational correctness surfaces + drills: typed telemetry, pipeline/DLQ inspection and replay, P2/P3 rebuild, currency-ledger audit | orchestration §6–7; D7, D60–D61 | WP-7.1 | telemetry/admin surfaces + deterministic drills | failures remain visible and drills pass without a dashboard or hosted control plane | done |
| WP-7.5 | **Hard-delete end-to-end**: purge active P1/P2/P3/K surfaces and prevent restore resurrection through the D74 portable manifest/adapter contract | hard-forget design; lifecycle §8; k_layers §10; S55 | D74 (gate #24 resolved) | forget pipeline | **S55 CI gate ON and green** across library-controlled surfaces + restore canary | done |
| WP-7.6 | **Release engineering**: semver across PyPI + the shared GHCR image + pinned compose; migrations-before-workers upgrade drill; quickstart cold-start release gate | packaging §1, §5–6; D62, D76–D77 | WP-7.1, owner release gates | release pipeline | tagged release produces all artifacts; upgrade drill green; quickstart under target | implemented (first-tag artifact proof remains) |
| WP-7.6 | **Release engineering**: semver across PyPI + the shared GHCR image + pinned compose; migrations-before-workers upgrade drill; quickstart cold-start release gate | packaging §1, §5–6; D62, D76–D77 | WP-7.1, owner release gates | release pipeline | tagged release produces all artifacts; upgrade drill green; quickstart under target | done |
| WP-7.7 | **Portable state + restore round-trip**: define the authoritative store set and fail-closed restore order; operators move bytes with native tools and projections rebuild normally | packaging §6; D7, D60, D74–D75 | WP-7.1, WP-7.5 | portability contract + deterministic drill | real PostgreSQL restore plus whole/independent external-store canaries → no resurrection + control green | done |

## WP-7.1 implementation
Expand Down Expand Up @@ -165,8 +178,7 @@ a reachable health endpoint.
[`RELEASING.md`](../../RELEASING.md) records the deliberately manual owner steps and the clean
verification commands. The repository rename, D77 risk acceptance, PyPI environment/pending
publisher, release-tag protection, and bounded-CLA enforcement are complete. The first tag now
supplies the artifact proof. Making the newly created GHCR package public remains the one
post-publish owner step rather than an OSS runtime feature.
supplies the artifact proof, and the versioned GHCR package is public for anonymous pulls.

## WP-7.7 implementation

Expand Down
2 changes: 1 addition & 1 deletion plan/plans/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ needs to restate it:
| 4 | Projections | P2 (spikes → views → rebuild → snapshots), P3 (tree + mounts incl. raw), communities | p2_graph, e0 §6, `p3_agent_navigation.md` | done (exit criteria met 2026-07-19; PRs #100-#104 — see the phase file) |
| 5 | Retrieval complete | full primitives + recipe registry, envelope contract CI, MCP/CLI, batch scan, **consumption skill + S58** | retrieval | done (exit criteria met 2026-07-20; PRs #105–#111 — see the phase file) |
| 6 | Plane K | planner/writer/driver, fact-sheet → prose bands, citations/staleness, authored + sidecars, triggers + subscriptions, K1 + K2 purpose scopes | k_layers | done (exit criteria met 2026-07-21; PRs #112–#117; former WP-6.7 removed by D73) |
| 7 | Operational correctness + portability | backfill/reprocessing, fixed scale batteries, configurable budgets, failure inspection/drills, hard-delete, release, portable restore | orchestration, packaging, schema §12–13 | implemented (all code and owner gates complete; first-tag artifact proof remains) |
| 7 | Operational correctness + portability | backfill/reprocessing, fixed scale batteries, configurable budgets, failure inspection/drills, hard-delete, release, portable restore | orchestration, packaging, schema §12–13 | done (exit criteria met 2026-07-23; PRs #120, #122–#124, #126, #128, #131; public `v0.1.0` release proof) |
| 8 | Competitive benchmarks | external benchmark harness, adapters, baselines (Mem0/Zep-class), capability benchmark, published methodology + results | D22 (internal) + `phase-8` survey | planned |

Sequencing calls already argued (see the phase files for the rest): **K after retrieval**
Expand Down
10 changes: 5 additions & 5 deletions website/src/app/docs/deployment/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ through conversion and deterministic structure, then leaves its chunk work
pending. Later pipeline workers are not yet wired into this quickstart. The
release workflow and tag-pinned Compose contract exist and trusted publishing is
configured. The bounded contributor agreement is enforced as a required `main`
check. No public PyPI or GHCR artifact exists yet because the first tag has not
been created.
check. The public `v0.1.0` release is available from PyPI, GHCR, and GitHub
Releases.
The RememberStack, `rememberstack`, and `remember` names used here are final. Do
not expose this stack to untrusted traffic.

Expand All @@ -31,9 +31,9 @@ cp .env.example .env
docker compose up --build --detach --wait
```

`--build` deliberately tests the checked-out source. A public tagged release
will also ship this Compose file pinned to the matching
`ghcr.io/writeitai/remember-stack` version; release consumers use
`--build` deliberately tests the checked-out source. The public `v0.1.0` release
also ships this Compose file pinned to
`ghcr.io/writeitai/remember-stack:0.1.0`; release consumers use
`--no-build --pull always` so Compose cannot fall back to a local source build.

The example file contains local-only PostgreSQL and MinIO credentials. Replace
Expand Down
2 changes: 1 addition & 1 deletion website/src/app/docs/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ export const metadata = {

**RememberStack** is a memory system for AI agents. It ingests heterogeneous inputs — documents, email, web pages, audio recordings, video, images — and distills them into progressively more abstract, navigable knowledge, while keeping every step auditable by humans. Scale is a requirement, not an aspiration: the system is designed to still be useful at a **million documents**.

> **Status: in development.** The design came first and is complete — requirements, architecture, research, and a decision log — and implementation is under way, following the [public roadmap](https://github.com/writeitai/remember-stack/blob/main/plan/plans/roadmap.md). There is no installable release yet. This site documents the system as it ships, page by page; the [Project Status](/docs/project-status) page tracks what exists today.
> **Status: pre-release.** Phases 0–7 are implemented, and [`v0.1.0`](https://github.com/writeitai/remember-stack/releases/tag/v0.1.0) is installable from [PyPI](https://pypi.org/project/rememberstack/0.1.0/) or as a public [GHCR container](https://github.com/writeitai/remember-stack/pkgs/container/remember-stack). Interfaces and the data model may still change before a stable release. The [public roadmap](https://github.com/writeitai/remember-stack/blob/main/plan/plans/roadmap.md) and [Project Status](/docs/project-status) page track what exists and what comes next.

## The problem it solves

Expand Down
Loading
Loading