3074417d64
GitHub is a push mirror of the Forgejo canon, not a peer. The sync force-matches refs, so every branch dependabot opens is deleted within the hour and its PR closes itself. Two runs proved it (checkout 4->7 and setup-node 4->7, both opened 2026-08-24, both auto-closed): the loop cannot land a change, and a public repo whose only PRs are self-closed bot PRs reads as abandoned. The bot's one useful output was taken by hand — publish.yml already pins actions/checkout@v7 and actions/setup-node@v7, shipped in 0.1.0. FORK.md records why, so restoring the file is a decision and not an oversight.
145 lines
6.9 KiB
Markdown
145 lines
6.9 KiB
Markdown
# RCLL as a fork of Hindsight
|
|
|
|
RCLL is a fork of [vectorize-io/hindsight](https://github.com/vectorize-io/hindsight)
|
|
(MIT, Copyright (c) 2025 Vectorize AI). This file records what we changed, where
|
|
we branched from, and how to take the next upstream release — the three things
|
|
the repository could not answer before, and the reason updating had become
|
|
archaeology instead of a rebase.
|
|
|
|
## What was wrong
|
|
|
|
The code arrived here on 2026-06-27 as a **single commit of 1716 files and
|
|
558,283 lines**, with no upstream remote and no common ancestor. Five later
|
|
commits carried branding only. So `git log` could tell you that a rebrand
|
|
happened and nothing at all about the engine changes underneath it — and
|
|
`git merge upstream/main` was not merely painful, it was *impossible*: unrelated
|
|
histories.
|
|
|
|
## Where we actually branched
|
|
|
|
Not from a release tag. The snapshot was matched against upstream commit by
|
|
commit, minimising the number of differing files:
|
|
|
|
| candidate | files differing from our tree |
|
|
|---|---|
|
|
| `v0.5.0` (2026-04-08) | 146 |
|
|
| `7b2263ba` (2026-04-13) | 34 |
|
|
| **`d054b884` (2026-04-10)** | **32** |
|
|
|
|
**Base = `d054b884`, "fix: add PEP 561 py.typed marker to all Python packages (#973)",
|
|
2026-04-10** — twelve commits past `v0.5.0`, which is why an earlier reading of
|
|
the delta against `v0.5.0` looked like 146 changed files and 13,383 inserted
|
|
lines. Most of that was upstream's own work between the tag and our branch
|
|
point, not ours. **Our real patch is 32 files.**
|
|
|
|
## The series
|
|
|
|
`rcll/main` replays that patch as nine commits on top of `d054b884`:
|
|
|
|
| commit | what |
|
|
|---|---|
|
|
| `chore: drop committed session keys and .DS_Store` | two `.sesskey` files and a `.DS_Store` that upstream had committed |
|
|
| `ci: replace upstream release pipeline with npm Trusted Publishing` | our publish workflow; upstream's four release/test workflows removed |
|
|
| `ops: standalone compose and env template` | `docker-compose.rcll.yml`, `.env.example`, standalone entrypoint |
|
|
| **`feat(rooms)`** | per-agent rooms, halls, durability layers — ADR-145. The one thing in this repo that is ours and has no upstream counterpart |
|
|
| **`feat(closets)`** | compression of memories by room+hall — ADR-145 phase 3 |
|
|
| **`feat(tunnels)`** | cross-bank memory bridges — ADR-145 phase 4 |
|
|
| `fix(engine)` | sync migration URL fallback, protected tables, small engine fixes |
|
|
| `feat(mcp)` | the RCLL MCP server and `server.json` registry manifest |
|
|
| `brand` | `README.md`, `RCLL.md` |
|
|
|
|
### How the split was verified
|
|
|
|
The series was not hand-sorted. [`scripts/rcll-split.py`](scripts/rcll-split.py) decomposes the
|
|
base→snapshot diff to **line granularity** — hunks are too coarse, because the
|
|
two largest are single appended blocks containing more than one feature — then
|
|
classifies every edit and materialises each stage by content.
|
|
|
|
Two checks, both mechanical:
|
|
|
|
* **Identity.** The tree at the last commit is byte-identical to the snapshot
|
|
tree (`git diff --quiet <series-head> <snapshot-tree>`). A split that lost
|
|
work could not pass this.
|
|
* **Each stage compiles.** Every intermediate commit is checked with
|
|
`py_compile` across `hindsight_api/`. This caught a real bug in the splitter:
|
|
a first version deleted base lines for not-yet-staged edits, which still
|
|
satisfied the identity check — because the final stage enables every group —
|
|
while corrupting all eight commits before it.
|
|
|
|
### Known imperfection, stated rather than hidden
|
|
|
|
Ten lines of tunnel code sit in the `feat(closets)` commit: one
|
|
`DELETE /tunnels/{id}` endpoint pair, plus the shared `_PROTECTED_TABLES` entry
|
|
that adds `"tunnels"` and `"closets"` on the same line. Rooms, closets and
|
|
tunnels are one ADR and genuinely share plumbing; this is where the automatic
|
|
boundary stops being sharp. Everything else separates cleanly (`rooms` contains
|
|
zero tunnel or closet lines; `tunnels` contains zero closet lines).
|
|
|
|
## Distance to upstream
|
|
|
|
As of 2026-08-23, upstream `main` is `3295716c` and the newest tag is `v0.9.1`
|
|
(2026-08-14). From our base that is **~1600 first-parent commits**, and the four
|
|
files our room/hall work touches most are also the four upstream rewrote most
|
|
(`memory_engine.py`, `http.py`, `orchestrator.py`, `retrieval.py`). Upstream has
|
|
**no room/hall/layer concept at all** — checked by grep against `main` — so
|
|
there is nothing to inherit and nothing to drop.
|
|
|
|
Our alembic line adds exactly one migration upstream does not have,
|
|
`aa1_add_room_hall_to_memory_units`. Production currently has **two alembic
|
|
heads** (`aa1_room_hall` and upstream's `h3i4j5k6l7m8`); any upgrade needs an
|
|
authored merge revision first.
|
|
|
|
## Taking the next upstream release
|
|
|
|
```
|
|
git fetch upstream --tags
|
|
git rebase --onto v0.9.1 d054b884 rcll/main # nine commits, not one blob
|
|
```
|
|
|
|
Conflicts land inside the feature commit that owns them, which is the entire
|
|
point of the series.
|
|
|
|
**Do not run migrations as part of this.** On Ring 0 the memory schema
|
|
`hindsight_v2` lives *inside* the CRM database, so an upstream migration is DDL
|
|
against a combat master, and 16 of the ~50 new ones are destructive
|
|
(`drop_memory_units_access_count`, `drop_entity_memory_links`,
|
|
`split_history_into_own_tables`, …). `HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP`
|
|
stays `false` there. Rehearse on a copy of the schema, never on the master.
|
|
|
|
## Remotes
|
|
|
|
```
|
|
origin https://github.com/holetron-lab/fleet-memory.git
|
|
upstream https://github.com/vectorize-io/hindsight.git (push URL deliberately
|
|
poisoned — nothing on
|
|
this box can push to
|
|
vectorize-io)
|
|
```
|
|
|
|
## What is deliberately NOT done here
|
|
|
|
`main` is untouched. Making `main` descend from upstream requires a force-push,
|
|
and this repository is one decision away from being made public with an already
|
|
published `server.json` — a rewritten history is a one-way door. The series
|
|
lives on its own branch; repointing `main` is the owner's call.
|
|
|
|
## Dependency updates: why there is no dependabot
|
|
|
|
`.github/dependabot.yml` was removed on 2026-08-28. It was not failing — it was
|
|
running in a loop that could never land.
|
|
|
|
GitHub is a **push mirror** of the Forgejo canon, not a peer. The mirror sync
|
|
force-matches refs, so a branch dependabot opens on GitHub is deleted within the
|
|
hour and its pull request closes itself. Two runs proved it (`bump
|
|
actions/checkout 4 → 7` and `bump actions/setup-node 4 → 7`, both opened
|
|
2026-08-24, both auto-closed). A public repository whose only pull requests are
|
|
self-closed bot PRs reads as abandoned, which is the opposite of what the bot is
|
|
for.
|
|
|
|
The bot's one useful output was taken by hand: `.github/workflows/publish.yml`
|
|
now pins `actions/checkout@v7` and `actions/setup-node@v7`, and that upgrade
|
|
shipped in the 0.1.0 release.
|
|
|
|
Action versions are therefore bumped on the canon, by hand, when the workflow is
|
|
touched. If GitHub ever becomes the canon rather than a mirror, restore the file
|
|
— the loop closes only because pushes are one-way.
|