0 Fork 0

Files

T

a3f09f4cac release: merge MemHub 1.0.4 development fixes (#50 )

* feat(memhub): add model usage audit and cost controls

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(memhub): typed source authorization state and managed-key registry ownership

Closes #29

Issue #29 surfaced as "WorkBuddy plugin cannot be uninstalled / source sync
cannot be turned on", but it is two independent failure domains that were both
being reported as a single opaque `desktop_action_failed`:

1. Source sync domain: the UI could not tell whether a source failed to sync
   because the grant was missing, revoked, or because the source identity or
   root path changed. Every failure collapsed into one error, so the UI could
   only say "failed".

2. Host plugin install domain: WorkBuddy shares three registry files
   (`known_marketplaces.json`, `installed_plugins.json`, `settings.json`) with
   the host. MemHub recorded a whole-file hash at install time and then refused
   to uninstall whenever the host (or a reformat) changed any byte anywhere in
   the file, even in entries MemHub does not own.

What changes

Domain errors (new `packages/host-bridge/src/domain-error.ts`)
- Closed allowlist `DOMAIN_CODES`: grant_required, source_identity_changed,
  host_uninstall_modified_managed_value, host_uninstall_unknown_owned_file,
  host_uninstall_needs_review, host_install_journal_invalid,
  host_install_recovery_required, host_permission_storage_unsafe.
- `DomainError` + `domainCodeOf()` so callers stop string-matching on
  `Error.message`. `diagnosticDomainError()` emits only the code and a
  repo-relative safe stack, never message text, so diagnostics cannot leak
  paths or payloads.
- Re-exported from `runtime-control` (host-bridge owns the type to avoid a
  dependency cycle); desktop `observeDesktopAction` now uses
  `domainCodeOf(error) ?? fallbackCode`.

Source authorization state
- `SourceAuthorizationState` enum: ok / missing_grant / revoked_grant /
  source_identity_changed / source_root_unavailable / candidate_changed, plus
  `SourceGrantStore.authorization_state()` which is read-only and fails closed.
- `/api/v1/sources` now returns `authorization_state` per source; contracts and
  the web app render a concrete next action next to the sync switch instead of
  a generic failure.
- `_change_source_sync` distinguishes sync_prepare_failed,
  sync_config_write_failed, sync_resume_failed, sync_watcher_failed (409 with
  the code as detail) while keeping the existing rollback behaviour.
- Capture refuses silently but now records a fail-open rejection marker
  (`sync_disabled` / grant_missing / grant_revoked) that counts occurrences in a
  time window and carries no payload, path, or session content.

WorkBuddy registry ownership (journal v1 -> v2)
- Ownership is now the value at MemHub's own key, not the whole file. Added
  `canonicalJson`, `registryManagedDigest`, `registryWithoutOurs`,
  `registryHoldsOnlyOurs`.
- Install: the plan records `keyPath` + managed digest; apply compares the
  managed value (CAS) instead of the whole file; the journal writes both the v1
  `installed_hash` and the v2 `installed_managed`.
- Uninstall: `resolveRegistryOwnership()` compares the v2 digest, falls back to
  the v1 hash and `isManagedRegistryEntry`, and otherwise produces a review
  finding instead of throwing. `managedRegistryRemoval()` deletes a file MemHub
  created when it still holds only our entry; removes just our key when the host
  has added its own content; and restores recorded bytes only when the rest of
  the document is unchanged, otherwise patches the current document.
- v1 journals migrate: a whole-file hash mismatch no longer blocks uninstall.

Tests
- `packages/host-bridge/src/domain-error.test.ts` (5): code is carried, message
  never reaches diagnostics, no guessing on unclassified errors, refuses to
  parse codes out of free text, allowlist is closed.
- `workbuddy-plugin-installer.test.ts` (34 total): uninstall survives a host
  reformat, removes only our key when the host changed something else, asks for
  review when a managed entry was changed, migrates a v1 journal, keeps a
  registry the host now uses, installs over a post-plan change.
- `apps/core/tests/test_source_authorization_state.py` (12): every state,
  fail-closed ordering, capture rejection names, marker contains no secret or
  path, recording never raises.
- `apps/web`: authorization note rendered for revoked grant and hidden when ok.

Verification
- host-bridge WorkBuddy suite 34/34; domain-error 5/5.
- apps/web 1906 tests across 105 files pass.
- pnpm -r typecheck clean; biome check clean on touched files.
- core-fast: 232 failed / 4131 passed, identical failure count to the clean
  baseline (232 failed / 4119 passed) with +12 from the new tests; the failures
  are pre-existing and unrelated (confirmed by stashing and re-running).

* feat(memhub): add a start/stop switch for model sedimentation

Shipped builds gave the user no way to stop model calls: the model content
permission switch is gone (removed with its endpoint in #20) and there is no
pause or remove entry either, so a configured model keeps turning
conversations into memories and keeps costing money.

Adds a user switch in settings: stopping keeps the model configuration and
the already imported conversations, leaves queued work pending instead of
failing it, and stops new work, enqueueing and backfill so nothing further
reaches the model. Starting again resumes the same work without re-entering
a key.

The flag lives in Core's own user config (config.json), so no schema
migration is needed, and the supervisor takes it as an optional callback so
every existing caller and test keeps its current behaviour.

* test(desktop): keep host-bridge mocks whole and assert the review contract

The memhub CI job failed four desktop tests after the issue #29 change. Both
were test-side contracts that the new ownership model intentionally moves, not
regressions in the fix itself.

1. `host-control-ownership.test.ts` mocked `@one-memory/host-bridge` with a
   whitelist that carried only `RecallBroker`. Main now imports `domainCodeOf`,
   which runtime-control re-exports from host-bridge, so the mock handed back
   undefined and every error path that called it threw a TypeError instead of
   the error the test was asserting on. The mock now spreads the real module
   and overrides only `RecallBroker`, which is the part it was written for.

2. `host-permissions.test.ts` asserted the pre-#29 contract, where a change
   anywhere in a shared registry made uninstall throw
   `host_uninstall_modified_files`. Ownership is now the value at our own key,
   so a change to that value is reported instead of guessed at: the plan
   schedules no removal, names the file in a review finding, and applying it
   refuses with `host_uninstall_needs_review`. The test keeps the guarantee it
   existed for, that those bytes are never overwritten, and now also asserts
   that apply refuses, so the safety is checked at both steps.

Verification: full desktop suite 38 files / 436 tests pass, `pnpm -r typecheck`
clean, biome reports only two pre-existing warnings on lines this change does
not touch.

* fix(logging): keep info diagnostics actionable

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(memhub): register the sedimentation switch test in the core test inventory

New core test files must appear in TEST_INDEX.md and in the classification
inventory's expected count and digest, and the backfill case needs a settled
turn because an unanswered user tail is not backfill material.

* feat(diagnostics): expose build info and fullscreen logs

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(settings): align help controls and tighten spacing

Co-authored-by: Cursor <cursoragent@cursor.com>

* release: prepare MemHub 1.0.4 build 8

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(memhub): clear pre-existing dev lint errors and flaky SDK dedup tests

Three things blocking CI that came in with dev and are unrelated to the
sedimentation switch itself:

- biome errors in DebugLogPanel.tsx (import order) and ModelUsageView.tsx
  (refreshToken is an intentional refresh trigger, annotated like the
  existing modelVersion trigger in R6Settings).
- test_extractor_prompt_override.py's fake LLM now accepts keyword args the
  real pipeline passes since the usage audit landed (audit_stage).
- the fake embeddings in the intention dedup tests used the process-random
  hash(), so two different texts collided roughly one run in 32 and were
  misread as duplicates; switched to a deterministic md5 index.

* fix(cli): count recall characters as code points

A recall whose hits contain an emoji outside the BMP was reported as
response_invalid even though the data and the search were fine: the CLI
cross-checked the response by summing String.prototype.length, which counts
UTF-16 code units, against Core's used_characters, which Python's len()
counts in code points. One emoji is two units here and one character there,
so any hit set with an emoji failed the check.

The sibling validator in host-bridge (context-protocol.ts) already counted
code points, so the CLI was the odd one out rather than a deliberate choice.

- validateContextResponse now sums through characterCount(), which counts
  code points, matching Core.
- Two regression tests: an emoji hit whose used_characters follows code
  points must stay grounded, and the same response counted as UTF-16 units
  must still be refused, so the cross-check is not simply loosened.
- The contract now states used_characters counts Unicode code points and is
  not an encoding length, so a client in another language does not repeat
  the comparison.

Verified by reverting the source change: the first test fails on the old
implementation and passes with it.

Closes #30

* fix(web): keep the model recovery entry reachable while a probe is pending

Closes #40

A pending model probe fenced the configuration editor, and the only
recovery entry ("核对测试结果") lived inside the area the fence kept
shut. Reaching it required opening the form; opening the form required
having recovered. People with a stuck probe could not change or repair
their model at all.

The fence itself was doing its job and still is. What was wrong is that
refusal also hid the way out.

R6Settings
- openConfiguration() now opens the model area whether or not the editor
  accepts, so the recovery entry inside it is reachable. editProfile()
  and add() still return false while the fence is up; nothing about the
  protection changed.
- The refusal notice is reworded to match: the configuration cannot be
  changed yet, and the next step is down in the area that just opened.
  Saying "cannot be opened" was both untrue now and unhelpful before.

ModelSettings
- A refused open is remembered instead of dropped. Once the fence clears,
  the intent is replayed, so the person lands in the form they asked for.
  Without this they would get a blank new-configuration form the moment
  the probe reconciled, which invites a duplicate entry.
- Replaying only fills fields in. It never sends a request, so no test is
  re-sent implicitly; "核对测试结果" remains the only thing that does.

Tests
- R6Settings: with a current model and without one, the recovery entry is
  reachable while the editor is fenced, and the refusal is still reported.
- ModelSettings: after reconciling, the form reopens on the profile that
  was asked for, and the probe is sent exactly once.
- Both new R6Settings cases and the ModelSettings case fail on the
  previous code.

* perf(runtime-control): decide runtime reuse before staging the payload

Every App launch copied the whole 373MB bundle into a temp directory and
hashed it twice before asking whether the selected runtime could be reused.
On a machine that already runs this build the answer is yes and all of that
work is thrown away: measured on a release Mac bundle, 6.9s to copy and
about 3.8s of hashing (fileDigests, then verifyInstalledDistribution over
the same tree).

installPackagedRuntime now describes the payload in place first. The staged
tree is a byte for byte copy of resources/{core,host-bridge,runtime,web}
plus two generated launchers, so the same relative paths and digests can be
read without copying anything. reuseSelectedSameBuild takes that description
instead of a staged directory, and only a payload that is going to be
installed is ever staged.

The decision itself is unchanged: it still compares every file digest except
bin/node, still repairs the packaged launcher when the App moved, and still
raises installed_version_conflict or distribution_hash_mismatch exactly as
before. Nothing was replaced by a cheaper fingerprint, because a wrong reuse
is what those errors exist to prevent.

Hashing also runs through a small worker pool now; the digests are identical
and the manifest keeps its sorted key order.

New test: describeBundlePayload must equal the manifest the staged copy
produces, so moving the decision ahead of the copy cannot decide something
different. Verified read-only against the installed release bundle:
1534 files, identical file sets, zero digest mismatches.

* perf(desktop): raise a startup window before the runtime and Core come up

Opening the App currently shows nothing at all until initialize finishes.
On this machine that is 55.6s from desktop.initializing to desktop.ready
(about 19s installing and starting the managed runtime, then about 36s for
Core to become ready), and window.requested is logged after desktop.ready.
A launch that slow with no window reads as a launch that failed, and people
click the icon again.

startDesktopLifecycle now takes two optional hooks. showStartupWindow runs
before initialize and loads a placeholder; revealStartupWindow runs after
initialize and swaps that same window onto the real app. Because the window
is reused rather than replaced, there is no second window and no flash.

The placeholder is served from the app protocol as /__startup, in memory,
not as a file in the web bundle. It performs no IPC: it renders before
initialize has registered a single handler, so anything it asked for would
fail and leave the page in an error state for the whole wait. That route is
also reserved, so a file of the same name inside the bundle can never be
reached through it.

Raising the placeholder is best effort. It only fills a wait that would
otherwise be blank; failing to draw it must not stop the services or the
real window.

Tests: five lifecycle cases cover the ordering (placeholder before
initialize, reveal after, reuse of the same window, nothing for a background
launch, and a real window when the placeholder was closed or could not be
raised). The four suites that mock ./app-protocol now spread the real module
instead of whitelisting it, which is what broke when the protocol gained
exports. host-control-ownership gains the BrowserWindow methods the
placeholder path uses, and its "no window" assertion now names the
placeholder, since a placeholder window is expected there by design.

* fix(core): stop the sedimentation switch failing its own request

Turning the switch off answered "停止未能确认，模型可能仍在整理记忆，请重试"
every time. The value was saved and the error was a lie the endpoint told
afterwards: `put_sedimentation` logged `memory_sedimentation.toggled` with
`details={"enabled": ...}`, `enabled` is not in the diagnostic allow-list, and
`_details` raises. That ValueError escaped the endpoint, so the request is
recorded in this machine's log three times as `api.request.failed` /
`core.request.unhandled` with `diagnostic_detail_key_invalid`, and the UI took
the 500 as an unconfirmed stop.

Because the raise sits between the save and the resume, starting again was
broken the same way: `resume_allowed()` never ran, so work parked by a stop
stayed parked.

Three changes, in the order they matter:

1. `enabled` is now a legal detail key. It is a bounded boolean, the same
   shape as `spawned` and `index_complete`.
2. `diagnostic_event` no longer lets a rejected payload reach the caller. It
   already swallowed `OSError` with the comment "Diagnostics must not become a
   new product outage"; an unlisted key is the same failure seen from the
   caller, and it is exactly what turned every external recall into a 500 and
   then killed the process last time. The payload is still wrong and still
   caught in CI — now by every module rather than five.
3. `test_diagnostic_payload_keys.py` walks every module instead of a
   hand-picked list. The two payloads that caused real outages were in files
   nobody thought to add to that list; the only shape of the check that holds
   the line is "every module, always". This file was already failing on dev
   with `api.py:3673: unlisted details key 'enabled'` — the bug was known to
   the suite and shipped anyway.

`DiagnosticLog.write` still raises, so the rejection itself is unchanged and
still tested; only the callers are protected.

* fix(core): let the drain claim a manual note's job

A memory added by hand stayed on "原话已保存，等待整理" indefinitely, with
`task_id: null`: the note's durable job was never claimed, so no task was ever
created for it. On this machine the job is still `pending` with `attempts=0`
more than eight hours after it was saved, while the write gate admits its
source without complaint.

The drain had two different answers to one question. `source_writes_permitted`
is `_source_writes_on`, which admits `one-memory-manual` by its grant. The
claim gate was `_config_store(app).sync_enabled`, the per-app toggle, and
`one-memory-manual` is not a connected app: it never appears in the
configuration document, so that predicate answers False for it. The job
survived the `enabled_sources` prefilter and was then dropped row by row, on
every tick, forever. Nothing ever failed and nothing ever ran.

The claim gate now asks the same question the write gate asks. Admission is
one decision; giving it two predicates is what parked the work.

Two tests pin it. One builds the drain as the composition root does and shows
the job is claimed, and shows the shipped wiring stranding the same job, so the
regression is visible if the toggle comes back. The other records the
asymmetry itself: `_source_writes_on` is True for the manual source while
`sync_enabled` is False, which is why the pair could disagree at all.

No migration and no reinstall: existing pending jobs are picked up on the next
drain tick.

* fix(memhub): make sedimentation pause stop model dispatch

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(memhub): schedule memory writes by event time

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(core): answer the sedimentation switch before the backlog walk

Turning "用模型沉淀记忆" back on wrote the choice to the store and then
awaited `resume_allowed()` inside the PUT handler. That call is not a nudge:
it runs maintenance over every unfinished task and then a whole-queue scan,
and the bounded scan waited -- holding the scan lock -- for the queue to drop
under its cohort ceiling. With a real backlog the queue never drops, so the
request never returned: one toggle in the field is still open 20+ minutes
later with no `api.request.completed`, while the renderer gave up at its 30s
timeout and showed "启用未能确认，仍显示上次确认的状态；请重试。" for a switch
that had in fact been saved.

The choice is the durable fact; the walk is follow-up work:

- The handler now stores the choice and returns it, and starts the resume as a
  watched background task (same idiom as the other Core background walks).
  Repeated toggles reuse the running walk instead of stacking.
- A bounded scan now stops at its ceiling instead of sleeping under the scan
  lock waiting for capacity, which also un-starves the periodic scan that was
  queued behind it. It reports `queue_saturated` rather than `no_tasks`, so
  the status stops claiming there is nothing to do while hundreds wait.

Verified on the field log first: the failing toggle is the only request in
the window with `api.request.started` and no `api.request.completed`, and its
trace shows `memory_sedimentation.toggled` succeeded 6ms in at
`pending_count` ~500. New tests fail on the old code (timeout) and pass now.

* fix(core): stop a blank author from erasing a whole conversation

A user turn whose host did not say who wrote it carries
`written_by=unknown`. The write binding's allow-list had every other
role/author pair but not that one, so verifying the context raised
`hy_memory_write_verification_context_scope` and the task ended as
`model_content_outcome_unknown` after two attempts: a memory the model may
well have written, that can never be confirmed, and a conversation that is
never sedimented again.

This is not a rare shape. On this machine 1078 user records across 1002
WorkBuddy conversations are `unknown`, and the failures were 42 per 15
minutes in the field log — every one of them a task reporting
`result_count=0` while 402 sat pending.

The author is missing, not the turn: the record is still inside the same
conversation, workspace and source, which is what the binding actually
checks, and the turn assembly already sent it. Accepting it here puts the
verification back in agreement with what was sent, the same reasoning that
added ("user", AGENT) for sub agent questions.

New test fails on the old code at hy_source_context.py:76 — the same frame
as the field stack — and passes now.

* fix(core): stop an abandoned read reporting a failure nobody owns

`in_read_pool` shields the wrapped worker, so a lane that runs out of budget
gives up on the answer without yanking a query out from under SQLite. The
caller cancels; the read runs on. When such an abandoned read then failed,
nothing awaited its future any more: `shield` drops its inner callback as soon
as the outer future is cancelled, so the inner future finished with an
exception that nobody retrieved. asyncio reports that at GC, and the loop
handler files it as `core.loop.task_exception` -- a red error sitting next to a
lane that had already degraded on its own budget and already said so.

On this machine that is the `raw_context_timeout` pair in the field log: a
Future, not a Task, carrying TimeoutError('raw_context_timeout'), reported
three times in half an hour. The lane result itself was right; only the
diagnostics were arguing with themselves.

Retrieving the outcome on completion keeps the diagnostics honest without
hiding anything: awaiting the read still raises for a caller who waited, which
the second case pins down.

The new case fails on the previous code (it reports the TimeoutError) and
passes now.

* fix(core): one task with no inputs no longer strands every unknown task

`MemoryTaskRunner._request` falls back to `chunk[0]` when no record is a
person-written user turn. A task whose inputs are gone yields an empty chunk,
so that fallback raised IndexError -- an error no caller can read. A reconcile
pass catches domain errors per task and moves on, so IndexError did not skip
the task: it ended the pass, and every unknown task behind it stayed unknown
while the retry backed off 1, 2, 4 ... 128 and gave up.

On this machine 68 of 303 unknown tasks had no inputs, which is exactly the
`reconcile_unknown / error_type=IndexError` backing off in the field log. Those
68 cannot be reconciled either way -- there is nothing to ask HY about -- but
the 235 that can must not be held hostage to them, and this is what stands
between a task whose model write may already have landed and its confirmation.

An empty chunk is now a domain error, so the pass skips the task and continues.
Also folds in one formatting hunk left over in this file from the previous
change, so the formatter is clean again.

The new case fails on the previous code at memory_processing.py:1036 with the
same IndexError the log shows, and passes now.

* chore(memhub): bump release build number to 10

The installer refuses a package whose bytes differ while its build number
stays the same, so the four Core fixes on dev need their own number to be
installable over the 1.0.4 / build 9 package already on the machine.

* fix(core): retire a window whose remaining rows FIFO refuses

The event-time window asked only whether its ten-minute range still held
*some* pending row before deciding the anchor was still active. A pending
row that FIFO holds back is not claimable: it may be blocked by an earlier
sibling of the same Harness whose own event time sits outside the range, and
that sibling can never be claimed from inside this window. The anchor then
stayed pinned forever and the whole queue starved.

Live shape on one machine: the anchor sat on 2026-10-07T03:24Z while the four
pending rows inside it were blocked by 929/930/1243/2347 earlier workbuddy
jobs, the earliest of them dated 2026-03-12. Completions stopped at 09:59 and
3.8k queued turns sat at zero output; restarting does not help because the
anchor is persisted.

The contract (docs/contracts/memory-event-time-scheduling-v1.md) retires a
window once every *eligible* pending/running row in the range has settled or
parked, and re-anchors on the next oldest eligible job. Reuse the claim's own
predicate — free lease, no busy Harness, no earlier unsent sibling — so "the
window is busy" and "the window can still be worked" finally agree. Anchor
selection and in-window selection already used it; only the liveness check
did not.

* fix(core): a refused source context is a failure, not an unknown write

Issue #44: an OpenCode import carried `role=user, written_by=unknown`. The
role/author set now admits it, but the row still never moved: `HyWriteBindings`
is built inside `ingest`, and the invocation marker is recorded *before* that
call, so the refusal arrived with the marker already set. The classifier
checked `hy_invoked` first and parked the task as `unknown` — a state that
means "HY may hold a write we cannot confirm" about a request that provably
never reached HY. The reason stayed off the row, the task could not be
re-driven, and the queue behind it stopped.

`hy_memory_write_verification_context_scope` is raised from that construction
alone, and `_check_source_context` (which does run after the call) raises
`hy_memory_evidence_changed` instead, so the code is unambiguous: nothing was
sent. It joins `PRE_SEND_REFUSAL_CODES`, and both classifiers now test that set
before the marker: the durable path settles `failed` with the marker cleared so
reclaim does not treat a row HY never saw as possibly-sent, and the task path
fails with the code instead of marking unknown.

Regression covers both directions: a pre-call refusal must end `failed` with
`hy_invoked=0`, and a post-call refusal (`authority_invalid`) must still be
`unknown` — the fix narrows the unknown set, it does not widen the failure set.

* chore(memhub): bump release build number to 11

Carries the window starvation fix (dc0ba49) and the pre-send refusal
fix (0df84c0). A new build number keeps the package distinguishable from
build 10 and lets it install over the current one.

* refactor(memhub): simplify durable memory scheduling

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(memhub): bump release build number to 12

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(security): parse diagnostic stack paths linearly

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(web): sync sedimentation switch status to home (#51)

---------

Co-authored-by: alvinfei <alvinfei@tencent.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: kristinhe <kristinhe@tencent.com>

2026-10-18 17:52:59 +08:00

18 KiB

Raw Blame History

MemHub / One Memory Architecture

Updated: 2026-10-16. This document describes the current MemHub implementation. Hy Memory is the SDK and engine. MemHub is the product and release name; One Memory / one-memory remains in historical module, storage, service, and compatibility interface names.

Product and Runtime Shape

MemHub is a local-first memory product. A user authorizes supported AI conversation sources, keeps their original content as local Evidence, processes eligible content through Hy Memory, governs the result, and grants hosts a separate scope for recall.

AI hosts and local conversation files
  ├─ historical import / incremental sync
  ├─ Host hooks, plugins, Skills and MCP
  └─ authorized recall
             │
             ▼
      Python Core / FastAPI
      ├─ source adapters and grants
      ├─ Evidence and import jobs
      ├─ durable memory_write_jobs
      ├─ per-job memory_tasks execution records
      ├─ model-content permission checks
      ├─ Hy Memory bridge
      ├─ Governance and retrieval
      └─ local HTTP API
          ▲        ▲         ▲
          │        │         └─ Host Bridge / recall broker
       Web UI    CLI / Runtime Control
                    ▲
                 Electron

There is one managed Runtime and one MemHub data home per installation. CLI and Electron are clients and lifecycle interfaces to that Runtime; they do not own separate memory stores or extraction engines. The Web UI is served or developed as a client of Core and does not access the database or host files directly.

Workspace Ownership

Path	Responsibility
`apps/core`	Python 3.12 / FastAPI data plane: SQLite business data, source adapters, Evidence, import and memory jobs, HY integration, Governance, retrieval, permissions, and API.
`apps/web`	React / TypeScript product UI and API client.
`apps/desktop`	Electron shell, native window and OS integration; attaches to or starts the managed Runtime.
`apps/cli`	Bootstrap, install, upgrade, service lifecycle, diagnostics, and user-facing commands.
`packages/runtime-control`	Runtime discovery and lifecycle, local installation transactions, service management, host setup control, and shared CLI/Desktop runtime contracts.
`packages/host-bridge`	Loopback recall broker and host-facing MCP, Skill, Hook, and plugin assets. It is not a second data plane.
`packages/contracts`	Shared TypeScript API contracts, aligned with Core's API models.
`packages/operations`	Shared typed operation flows used by clients.
`scripts`	Development, privacy, test, packaging, and release gates; not runtime product code.

Python dependencies and Core tests are managed by uv; the TypeScript workspace is managed by pnpm. The repository requires Node.js 24 and Python 3.12. See the root package.json, apps/core/pyproject.toml, ../README.md, and ../CONTRIBUTING.md for executable commands and contribution rules.

Data and Processing

Source authorization and synchronization

Source root authorization and Harness synchronization are distinct:

SQLite source_grants records the authorized root, its identity, grant and revocation state. A grant does not by itself turn synchronization on.
Core-owned <data_dir>/config.json is the durable desired state for sync_enabled per source. The embedded Hy Memory SDK is part of MemHub and may use the complete local memory store; there is no second model-content permission switch.
Core is the only writer of config.json. It validates a strict schema and persists updates through a private temporary file, fsync, atomic replace, and directory fsync.
Web, Desktop, CLI, and Runtime call Core APIs; they do not edit the file or keep a second durable copy of these settings.

Turning sync on requires an authorized source root, prepares catch-up import work, commits the desired state, then activates scanning. Historical complete turns that do not yet have a durable write receipt are added to memory_write_jobs. Startup performs the same reconciliation for sources that are enabled in config.json.

Turning sync off has two effects for that Harness: scanning stops, so future content creates no new write job; and the drain stops claiming its pending jobs. A job that was claimed but has not made its first HY/model call is released back to pending. A job that has already started its first HY/model call is allowed to finish the whole job. Previously published memories remain available for authorized recall.

Periodic polling and optional filesystem watch live in Core. The Web UI does not schedule scans. Historical import and live notifications converge on the same source identity, Evidence, and import-job model.

Adapters may read authorized host files, including a host application's own SQLite database. They do not write MemHub's database and do not call HY directly. Source readers retain path containment, root/file identity, symlink-refusal, and cursor/anchor checks.

Memory processing

The normal content path is:

authorized source
  -> Evidence
  -> import job / complete conversation turn
  -> memory_write_jobs
  -> persisted event-time window
  -> durable drain
  -> memory_tasks internal execution record
  -> sedimentation and source gates
  -> Hy Memory bridge
  -> write verification and Governance
  -> search / recall / UI

Evidence is stored before model work so processing failures do not discard source content. Complete-turn preparation preserves user, assistant, and tool roles and their authorship. Historical recovery, scanner callbacks, live notifications, manual memory input, and Matter discovery all submit to the same durable memory_write_jobs table. They do not invoke HY directly.

memory_write_jobs is the sole production intake and scheduling queue. Every row receives the complete turn's event_at, a time_quality, and a persistent monotonic queue_seq. The drain anchors a fixed ten-minute window at the oldest eligible event time. Different Harnesses may run concurrently inside that window, while each Harness remains FIFO by queue_seq; live priority metadata never jumps the event-time window. The persisted anchor prevents a restart or a chain of nearby jobs from sliding the window forward.

First onboarding imports are a barrier: accepted Harnesses finish importing the shared history cutoff and submit their chunks before the drain begins model work. Failed or explicitly disabled sources are excluded rather than blocking the user's whole timeline. See contracts/memory-event-time-scheduling-v1.md.

memory_tasks remains as an internal execution, lease, input, output, and reconciliation record created while a claimed write job runs through HY. It is not independently recovered or scheduled by the production composition root. The legacy ProcessingCoordinator and supervisor backfill/resume scheduler are not started by Core; history recovery writes durable jobs instead.

The synchronization API and the first HY-call boundary use the same sedimentation/source locks. If pause commits first, the job cannot cross into HY and returns to pending. If the job records its first HY invocation first, pause does not interrupt that in-progress job. Lease expiry after a possible HY call remains unknown, never a blind retry.

HY and Governance

Hy Memory is the underlying extraction, memory, and semantic retrieval framework. Product code enters it through HyMemoryBridge and the permission transport, not by constructing an SDK client in feature code.

The bridge and Governance layer preserve Evidence references, authorship, scope, write verification, revisions, corrections, and deletion behavior. A successful SDK response alone is not sufficient evidence of a product-level write. Retrieval results are checked against current Governance and access scope before being returned to the UI or an authorized host.

The currently pinned SDK is the public PyPI distribution hy-memory==2.0.4. Runtime configuration and permission boundaries are documented in ../MEMORY.md.

Permission Boundaries

These permissions answer different questions and must not be collapsed:

Source grant: may Core read this selected host data root?
Harness sync: should Core continue discovering and importing changes from this source?
Model-content permission: may eligible local conversation content be sent to the configured model provider?
Host recall grant: may this external host retrieve specified memory scopes or use specified tools?

Model-content permission is a global final-state setting in config.json. Tasks do not carry a parallel permission receipt or per-task model permission ledger. A live permission guard rechecks the current setting and active model profile at remote-send and publication boundaries. Revocation therefore cannot be inferred from an old task snapshot.

Host installation and recall authorization can modify or expose configuration in another process. Their preview, fingerprint, scope, credential, and rollback protections remain because they cross an external trust boundary. These do not turn Harness sync into a multi-step external operation.

The product must not depend on screen capture, Accessibility/AXTree, OCR, keyboard/mouse, clipboard, or background audio collection.

Storage

SQLite is the sole authoritative MemHub business database, under the user's One Memory Home (normally ~/.one-memory). It stores Evidence, grants, import jobs and cursors, memory tasks, Governance, model profiles, and other product state. Runtime versions and npm packages are not the data directory.

HY-owned vector, graph, cache, and history stores are managed according to the HY SDK contract under the One Memory Home. They are not a second authoritative MemHub business database. Adapters may separately read a host's own database under the source grant.

MySQL-only business storage was an earlier proposal and is not the active architecture. Decision D56 selected SQLite and superseded D53. Do not add a MySQL runtime, fallback, dual-write path, or SQLite-to-MySQL migration as part of ordinary development. Historical migration research and records may remain in dated documents, but they are not implementation instructions.

config.json contains desired user settings, not runtime health, source-root grants, cursors, or job state. Runtime state is reconstructed from durable settings and database state.

Runtime and Interfaces

The repository has one Runtime implementation, one default data home, and one operating-system service identity per installation. The macOS App and npm CLI share the Runtime artifact contract, ~/.one-memory, receipts, ports, credentials, Core API, single-writer lock, stable install root, and service declaration.

Runtime process shape

The long-running Runtime is a Node process running runtime.cjs serve. It owns:

one Python Core child;
one recall Broker / Host Gateway sidecar;
the Runtime, Core, Broker, token, and lock receipts under the data home;
Core restart supervision while the Runtime process remains alive.

The Electron UI and the npm CLI are control surfaces. They discover the Runtime through those receipts and verify its loopback identity before attaching. The Core's data-directory lock prevents a second Core writer, but that lock is not a replacement for having one unambiguous operating-system startup owner.

macOS App path

A production App under /Applications performs a managed installation before attaching its UI:

Copy the bundled Runtime into ~/Library/Application Support/One Memory/{versions,current}.
Install the stable ~/.local/bin/memhub link.
Write an App-owned service receipt under ~/.one-memory.
Install or migrate the single ~/Library/LaunchAgents/com.tencent.onememory.runtime.plist declaration.
Wait for the Runtime, Core, and Broker to become verifiably ready.
Attach Electron as a client of that Runtime.

The LaunchAgent starts current/bin/node current/runtime/runtime.cjs serve directly. It does not start Electron and does not open a window:

macOS user login
  -> com.tencent.onememory.runtime LaunchAgent
  -> managed Runtime
  -> Python Core + Broker

Electron App -> attach/control only

The old SMAppService.mainAppService registration is read only for migration: an App launched by the old login item stays hidden for that launch, then the old registration is disabled. It is not a second startup owner.

Closing all windows or fully quitting Electron releases the UI's attachment but does not stop the managed Runtime. The explicit login-start preference controls a private runtime-service.enabled marker used by launchd's KeepAlive.PathState; disabling it affects future login/restart behavior but does not interrupt the currently running Runtime.

An App-owned service records the exact /Applications/...app bundle and executable paths. The Runtime checks them before starting Core and while running. If the App is deleted, it removes the enable marker and exits cleanly. The stable bin/node launcher performs the same check before invoking Electron, covering the case where the Runtime was already stopped when the App was deleted. With the marker absent, launchd does not restart the job. User Memory data and the stable Runtime files remain until an explicit uninstall/delete operation.

npm Bootstrap / CLI path

The public installation design is a lightweight npm Bootstrap CLI plus an independently acquired Runtime. The Bootstrap package does not contain the Python Core, Web UI, Host Bridge, model assets, or a full Runtime. An explicit memhub install --yes resolves and verifies the release, installs the Runtime, installs CLI links, registers the user service, starts it, and waits for verified Core readiness in one rollback-capable transaction.

Bootstrap CLI
  -> release manifest and artifact verification
  -> safe extraction to a private staging directory
  -> managed Runtime install transaction
  -> user-level service
  -> Python Core + Host Gateway

On macOS, the CLI-managed service uses the same user LaunchAgent at ~/Library/LaunchAgents/com.tencent.onememory.runtime.plist. It does not use RunAtLoad; conditional KeepAlive.PathState watches the private enable marker, and an explicit install/start bootstraps the declaration. It launches current/bin/node current/runtime/runtime.cjs serve. On Linux, it is a systemd user service enabled for default.target, with restart-on-failure and bounded restart backoff. Both are user services: they start after the user's service/login session exists, not as a pre-login system daemon.

Install and upgrade preserve managed-install checks, health validation, and rollback behavior. npm uninstall removes only the Bootstrap CLI. memhub uninstall removes the managed service, Runtime and managed links while keeping Memory data by default. delete-data is a distinct confirmed operation.

Current lifecycle matrix

Scenario	Startup owner	After user login	Full UI quit	App deletion	Process-level recovery
macOS App-owned	LaunchAgent	Runtime/Core/Broker start without Electron	Runtime continues	Marker removed and Runtime stops; no restart	launchd restarts Runtime; Runtime restarts Core
macOS CLI-owned	Same LaunchAgent	Runtime/Core/Broker start without Electron	No Electron dependency	GUI App deletion has no effect	launchd restarts Runtime; Runtime restarts Core
Linux CLI-owned	systemd user service	Runtime starts with the user manager/default target	No UI dependency	Not applicable	systemd restarts Runtime; Runtime restarts Core

The background Service therefore remains available when the Electron UI is not running. Stopping Runtime, disabling login start, uninstalling Runtime, and deleting data remain distinct operations.

Service ownership

There is exactly one startup owner per data home:

macOS LaunchAgent or approved managed helper
Linux systemd user service
              -> managed Runtime
              -> Core + Broker

Electron App -------- attach/control only
npm CLI ------------- attach/control only

The owner receipt is app or cli. A full memhub install --yes or successful CLI upgrade transaction can take ownership before starting the service and rolls the owner back on failure. Once CLI-owned, deleting the GUI App does not stop the service. Merely running service-install does not claim the Runtime; it only repairs/registers the current owner's service.

Release acceptance covers logout/login, complete Mac reboot, notarization, staple, Gatekeeper, and clean-machine installation. Acceptance evidence is stored with release artifacts rather than in the source tree.

The Host Bridge exposes only loopback services and host-scoped capabilities; it does not persist a general-purpose Core bearer token or provide an unrestricted Core proxy.

Current Support and Release Boundary

Support is declared per immutable GitHub Release manifest:

Linux x64 and arm64 Runtime artifacts are built and verified on native GitHub Actions runners.
macOS arm64 and x64 App/Runtime artifacts must carry Developer ID signatures, notarization tickets, and native-platform acceptance receipts.
Windows is not supported.
hy-memory==2.0.3 is the public Python SDK dependency.

See INSTALLATION.md for the release matrix. A source test, fake hosting test, or cross-build does not substitute for a native-platform lifecycle receipt.

Engineering Rules

Preserve the source record before model processing.
Keep source authorization, model egress consent, and host recall scope independent.
Do not treat unavailable source data as deletion.
Do not create confirmed memory without supporting evidence.
Keep claims traceable to the narrow original Evidence that supports them.
Do not let graph layout imply semantic relationships.
Run the smallest directly relevant tests for ordinary development.
Run full suites, release gates, packaging, live, soak, or cross-platform acceptance only when explicitly requested or authorized for release work.
Never remove a safety boundary merely to make a test or release gate green.

The current test entry points are documented in ../CONTRIBUTING.md.

18 KiB Raw Blame History