Skip to content
Closed
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
44 changes: 34 additions & 10 deletions docs/memory-plugin-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -315,7 +315,7 @@ imported.

## 7. EverOS version pinning & upgrade SOP

### 7.1 Exact pin is mandatory **[DONE: `everos[multimodal]==1.2.3`]**
### 7.1 Pin to one minor line **[DONE: `everos[multimodal]>=1.4.1,<1.5`]**

The adapter is written against EverOS **internal** APIs, not a stable
public surface:
Expand All @@ -328,27 +328,31 @@ public surface:
`everos.service.memorize._get_engine`,
`everos.infra.persistence.sqlite.md_change_state_repo`

Any release — even a patch — can move these symbols. Therefore EverOS
is pinned to an exact version (`==X.Y.Z`), not a range: upgrades are
deliberate, re-validated events, never something `uv lock --upgrade`
can do silently.
Any release — even a patch — can move these symbols. EverOS is held to
one minor line (`>=X.Y.Z,<X.(Y+1)`): a patch release may follow through
`uv lock --upgrade`, which accepts that risk for patches, while a minor
or major bump stays a deliberate, re-validated event. The lock still
names one exact version and the release's `raven-constraints.txt` is
exported from it, so an install from a release gets that version and no
other.

Single pin: with `raven_everos` removed, EverOS is pinned in **one**
place (raven's `pyproject.toml`). The upgrade surface is one line.
Single pin: EverOS is pinned in **one** place, the plugin's
`plugins-dist/everos-memory/pyproject.toml`. The upgrade surface is one
line.

### 7.2 Upgrade procedure

0. **Assess**: read the EverOS changelog; check whether the internal
symbols above moved, and whether the on-disk schema
(`~/.everos/.index/` sqlite + lancedb) changed.
1. **Bump the pin (uv only — never hand-edit pyproject/lock)**:
1. **Move the range (uv only — never hand-edit pyproject/lock)**:
```bash
uv add 'everos[multimodal]==1.2.3' && uv sync
uv add --package everos-memory 'everos[multimodal]>=1.4.1,<1.5'
```
Always keep the `[multimodal]` extra. Skip `1.2.0`: it shipped a
path-traversal regression fixed in `1.2.1`.
2. **Adapt the adapter** if symbols/signatures changed — only
`raven/plugin/memory/everos/`. Re-check version assumptions
`plugins-dist/everos-memory/raven_everos/`. Re-check version assumptions
written in adapter comments.
3. **Test (all three layers)**:
```bash
Expand Down Expand Up @@ -418,6 +422,26 @@ until the session restarts. And `everos cascade rebuild`, now the
supported index recovery, refuses to run while a server holds the OME
lock — while raven exposes no way to stop the server it started.

### 7.4 Record: `1.2.3` -> `1.4.1`

Five lock entries moved: `everos`, `everalgo-boundary` `0.2.0` -> `0.2.1`,
`everalgo-core` `0.4.0` -> `0.3.0` (everos pins it exactly since `1.3.0`),
`pyarrow` `24.0.0` -> `25.0.1`, and `msvc-runtime` added on Windows only.
Every internal symbol listed in 7.1 is present in `1.4.1`, and
`MemorizeAddRequest.messages` still carries `min_length=1`.

**No data migration.** The `subject_vector` column that `1.4.0`'s
startup schema check requires already existed in `1.2.3`, so an index
written by `1.2.3` opens as is. The first server start builds an
IVF_FLAT index on every vector column past 2000 rows (seconds per 10k
rows; searches keep working on a flat scan meanwhile). Vector search has
used cosine on every path since `1.3.0`, so ranking can shift slightly
on an existing store. `POST /memory/add` answers 422 instead of 500 to a
`role = "tool"` message without `tool_call_id`; the adapter already
treated any status error as that one write refused, so nothing changes
on its side. `1.4.1` itself only pins `openai<3`, which a fresh install
needs since openai 3.x broke every LLM call.

---

## 8. Validation (this change)
Expand Down
8 changes: 4 additions & 4 deletions plugins-dist/everos-memory/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@ classifiers = [

dependencies = [
"raven",
# The substrate this adapter binds. Exact pin, not a range: the adapter
# reaches internal (non-public) everos APIs, so an upgrade is a deliberate
# act. Same pin the host carried while the plugin lived inside it.
"everos[multimodal]==1.2.3",
# The substrate this adapter binds, held to one minor line: the adapter
# reaches internal (non-public) everos APIs, so a minor or major bump is a
# deliberate act; a patch release may follow through `uv lock --upgrade`.
"everos[multimodal]>=1.4.1,<1.5",
"httpx>=0.28.0,<1.0.0",
"loguru>=0.7.3,<1.0.0",
"tomli-w>=1.2.0",
Expand Down
4 changes: 2 additions & 2 deletions plugins-dist/everos-memory/raven_everos/backend.py
Original file line number Diff line number Diff line change
Expand Up @@ -1432,8 +1432,8 @@ async def feedback(self, signals: dict[str, Any]) -> None:

The host already collects ``skill_usage`` signals (which everos
skills were injected / used in a turn) and dispatches them here.
everos 1.2.3's HTTP surface still exposes no endpoint to consume
them — its routes are get / health / knowledge / memorize /
everos 1.4.1's HTTP surface still exposes no endpoint to consume
them — its routes are cascade / get / health / knowledge / memorize /
metrics / ome / search, and ``agent_skill.confidence`` lives in
the persistence internals with no service-level write path — so
signals are dropped until everos grows one. The method stays on the Protocol because it is
Expand Down
2 changes: 1 addition & 1 deletion tests/test_everos_backend.py
Original file line number Diff line number Diff line change
Expand Up @@ -1855,7 +1855,7 @@ async def test_a_service_that_was_never_configured_reports_no_failure(self) -> N
class _SchemaStrictAdapter:
"""A fake that refuses what production refuses.

everos 1.2.3 declares ``MemorizeAddRequest.messages`` with
everos 1.4.1 declares ``MemorizeAddRequest.messages`` with
``min_length=1``, so an add carrying an empty list is a 422 and the flush
behind it never goes out. A fake that accepts the empty add hides exactly
that, which is how a shutdown flush that never reached the server passed
Expand Down
Loading
Loading