KofTwentyTwo/Jarvis
2
0 Fork 0
Code Issues 111 Pull Requests 16 Actions Packages Projects Releases 4 Wiki Activity

M-4: Memory surface (factMutated/factsRetrieved/searchFacts; cache-eligibility regression gate) #8

New Issue
Open
opened 2026-05-12 19:02:19 +00:00 by KofTwentyTwo · 0 comments
KofTwentyTwo commented 2026-05-12 19:02:19 +00:00 (Migrated from github.com)
Copy link
Copy source

Goal

Land Memory surface. factMutated / factsRetrieved / searchFacts / forgetFact / listRecentFacts / listTurns through the typed API. Cache-eligibility regression gate (R-006) pins behavior of the B-02 tactical patch against the new surface.

Scope — surfaces in this phase

  • JarvisAPI.Memory queries: listRecentFacts, searchFacts, listTurns (substrate-side helper; listTurns lives on Turn surface per F-008)
  • Commands: forgetFact (no requiresConfirmation param — F-009; confirmation via ConfirmationBroker test seam under UQ-1)
  • Events: factMutated, factsRetrieved — REPLACE old replay-event emit, do not parallel-emit
  • searchFacts returns Result<MemoryHits, MemoryError> with .vectorIndexUnavailable triggerable under harness (R-011 typed degraded result)
  • Orchestrator history-load uses Memory surface helper (reframes B-02 patch)
  • getSelfState.memoryVectorAvailable: Bool reflects current dylib load state

Files (created/modified)

  • packages/JarvisAPI/Sources/JarvisAPI/Surfaces/Memory+Adapter.swift (new) — wraps MemoryStore
  • packages/AgentCore/Sources/AgentOrchestrator/AgentOrchestrator.swift — history-load via Memory surface
  • packages/Memory/Sources/Memory/MemoryStore.swift — delete legacy replay-event emit site
  • packages/Harness/Tests/HarnessTests/MemoryScenarioTests.swift (new)

Test contract

Scenarios S-MEM-001..S-MEM-008 per JARVIS-API-TEST-CONTRACT.md:

  • Non-vector scenarios run in BOTH transport modes
  • Vector scenarios gated JARVIS_REAL_MODELS=1 (skipped in default swift test; required for PR merge if D-5/D-6/D-7 closed — see Path A vs Path B in plan §7)
  • S-MEM-CACHE-REGRESSION (BLOCKING): two short turns then a third produces ZERO streamTruncated retries — pins R-006 mitigation post-B-02 patch
  • FTS-only path testable with StubEmbedder

Acceptance criteria

  • bash scripts/check-single-memory-mutated-emit.sh green AFTER migration (literal moved to new site; gate updated)
  • bash scripts/check-single-memory-used-emit.sh green
  • bash scripts/check-embedding-dim-literal.sh green
  • R-006 regression gate (BLOCKING): S-MEM-CACHE-REGRESSION produces zero streamTruncated retries
  • All Memory scenarios green via .inProcessActor runner
  • All Memory scenarios (non-vector) green via .jsonRoundTripWebView runner
  • getSelfState.memoryVectorAvailable reflects current state; harness asserts at boot
  • M-4 PR description includes explicit D-5/D-6/D-7 declaration (Path A vs Path B)
  • PR merged to develop

Carry-forward closures

  • B-02 already closed 2026-05-11 (tactical patch); M-4 reframes against the API + pins behavior via cache-eligibility regression gate

Dependencies

  • Blocked by: #7 (M-3); D-5/D-6/D-7 status declared at PR open time
  • Blocks: #9 (M-5 Vision)

Related issues

  • D-7 partial: nomic-embed-text installed; qwen2.5-coder:32b currently only :32b-instruct-q8_0 variant available
  • May dissolve M-1 memory-audit findings (facts_vec writes, FTS5 query syntax)

Sub-issues

  • #115 — M-4: define JarvisAPI.Memory protocol + adapter (listRecentFacts/searchFacts/listTurns)
  • #116 — M-4: Memory.forgetFact command (F-009 — no requiresConfirmation transport leak)
  • #117 — M-4: factMutated + factsRetrieved events; delete legacy emit (R-017)
  • #118 — M-4: Memory.searchFacts typed degraded result + memoryVectorAvailable flag (R-011)
  • #119 — M-4: orchestrator history-load via Memory surface + cache-eligibility regression gate (R-006)
  • #120 — M-4: harness scenarios S-MEM-001..008 + S-MEM-CACHE-REGRESSION (UQ-5)

Estimate

2.0–3.0 engineer-days

Source

  • .planning/architecture/JARVIS-API-MIGRATION-PLAN.md §2.5 + §7 (D-5/D-6/D-7 dependency)
  • .planning/architecture/JARVIS-API-DESIGN-v0.1.md — Memory surface
  • .planning/architecture/JARVIS-API-DESIGN-v0.2.md — F-008, F-009, F-021
  • .planning/architecture/REVIEW-MIGRATION-RISK.md R-006, R-011, R-017
  • Parent epic: v1.0 API Migration — UI/Backend separation (M-0..M-7) (#76)
## Goal Land Memory surface. `factMutated` / `factsRetrieved` / `searchFacts` / `forgetFact` / `listRecentFacts` / `listTurns` through the typed API. Cache-eligibility regression gate (R-006) pins behavior of the B-02 tactical patch against the new surface. ## Scope — surfaces in this phase - **`JarvisAPI.Memory`** queries: `listRecentFacts`, `searchFacts`, `listTurns` (substrate-side helper; `listTurns` lives on Turn surface per F-008) - Commands: `forgetFact` (no `requiresConfirmation` param — F-009; confirmation via `ConfirmationBroker` test seam under UQ-1) - Events: `factMutated`, `factsRetrieved` — **REPLACE** old replay-event emit, do not parallel-emit - `searchFacts` returns `Result<MemoryHits, MemoryError>` with `.vectorIndexUnavailable` triggerable under harness (R-011 typed degraded result) - Orchestrator history-load uses Memory surface helper (reframes B-02 patch) - `getSelfState.memoryVectorAvailable: Bool` reflects current dylib load state ## Files (created/modified) - `packages/JarvisAPI/Sources/JarvisAPI/Surfaces/Memory+Adapter.swift` (new) — wraps `MemoryStore` - `packages/AgentCore/Sources/AgentOrchestrator/AgentOrchestrator.swift` — history-load via Memory surface - `packages/Memory/Sources/Memory/MemoryStore.swift` — delete legacy replay-event emit site - `packages/Harness/Tests/HarnessTests/MemoryScenarioTests.swift` (new) ## Test contract Scenarios `S-MEM-001..S-MEM-008` per `JARVIS-API-TEST-CONTRACT.md`: - Non-vector scenarios run in BOTH transport modes - Vector scenarios gated `JARVIS_REAL_MODELS=1` (skipped in default `swift test`; required for PR merge if D-5/D-6/D-7 closed — see Path A vs Path B in plan §7) - `S-MEM-CACHE-REGRESSION` (BLOCKING): two short turns then a third produces ZERO `streamTruncated` retries — pins R-006 mitigation post-B-02 patch - FTS-only path testable with `StubEmbedder` ## Acceptance criteria - [ ] `bash scripts/check-single-memory-mutated-emit.sh` green AFTER migration (literal moved to new site; gate updated) - [ ] `bash scripts/check-single-memory-used-emit.sh` green - [ ] `bash scripts/check-embedding-dim-literal.sh` green - [ ] **R-006 regression gate (BLOCKING):** `S-MEM-CACHE-REGRESSION` produces zero `streamTruncated` retries - [ ] All Memory scenarios green via `.inProcessActor` runner - [ ] All Memory scenarios (non-vector) green via `.jsonRoundTripWebView` runner - [ ] `getSelfState.memoryVectorAvailable` reflects current state; harness asserts at boot - [ ] M-4 PR description includes explicit D-5/D-6/D-7 declaration (Path A vs Path B) - [ ] PR merged to develop ## Carry-forward closures - B-02 already closed 2026-05-11 (tactical patch); M-4 reframes against the API + pins behavior via cache-eligibility regression gate ## Dependencies - Blocked by: #7 (M-3); D-5/D-6/D-7 status declared at PR open time - Blocks: #9 (M-5 Vision) ## Related issues - D-7 partial: nomic-embed-text installed; qwen2.5-coder:32b currently only `:32b-instruct-q8_0` variant available - May dissolve M-1 memory-audit findings (facts_vec writes, FTS5 query syntax) ## Sub-issues - #115 — M-4: define JarvisAPI.Memory protocol + adapter (listRecentFacts/searchFacts/listTurns) - #116 — M-4: Memory.forgetFact command (F-009 — no requiresConfirmation transport leak) - #117 — M-4: factMutated + factsRetrieved events; delete legacy emit (R-017) - #118 — M-4: Memory.searchFacts typed degraded result + memoryVectorAvailable flag (R-011) - #119 — M-4: orchestrator history-load via Memory surface + cache-eligibility regression gate (R-006) - #120 — M-4: harness scenarios S-MEM-001..008 + S-MEM-CACHE-REGRESSION (UQ-5) ## Estimate 2.0–3.0 engineer-days ## Source - `.planning/architecture/JARVIS-API-MIGRATION-PLAN.md` §2.5 + §7 (D-5/D-6/D-7 dependency) - `.planning/architecture/JARVIS-API-DESIGN-v0.1.md` — `Memory` surface - `.planning/architecture/JARVIS-API-DESIGN-v0.2.md` — F-008, F-009, F-021 - `.planning/architecture/REVIEW-MIGRATION-RISK.md` R-006, R-011, R-017 - Parent epic: #76
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
area:agent
area:build
area:bus
area:devtool
area:hud
area:logging
area:mcp
area:memory
area:vision
area:voice
audit-finding
bug
Something isn't working
 carry-forward
comment-cleanup
Comment / docstring cleanup per .planning/code-commenting-guide.md
 dependencies
Dependency updates
 documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 epic
good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 javascript
Pull requests that update javascript code
 migration
question
Further information is requested
 severity:critical
severity:high
severity:low
severity:medium
wontfix
This will not be worked on
No labels area:memory epic migration
Milestone
No items
No Milestone v0.8 — API M-4..M-7 (Memory / Vision / Voice / Turn surfaces)
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#8