0 Fork 0

Files

T

james.maesandClaude Opus 4.7 508cf924d0 docs(packages): per-package README files

Adds README.md to each of the 13 SPM packages (AgentCore, Bus, Config,
DevOverlay, Harness, Keychain, Logging, MCP, Memory, Replay, Shell, Vision,
Voice). Each covers purpose, key public types, deps, consumers, invariants
(pulled from CLAUDE.md + grep-gates + audit findings), test stack, and
notable files. Memory README explicitly marks the package functionally OFF
until vec0.dylib + Ollama models land.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-04 17:13:33 -05:00

3.5 KiB

Raw Permalink Blame History

Memory

Long-term fact store + extraction pipeline. SQLite (FTS5 + sqlite-vec) at ~/Library/Application Support/Jarvis/jarvis.db; mem0-style ADD/UPDATE/NOOP extraction; hybrid keyword + vector search via Reciprocal Rank Fusion.

Functional state. Memory is code-complete but functionally OFF until vec0.dylib ships (Track D-5/D-6 — user environment work) and ollama pull nomic-embed-text runs (D-7). installMemory degrades gracefully — extractor + orchestrator + coordinator construct even when MemoryStore init throws.

Key public types

Type	Purpose
`MemoryStore` (actor)	The only writer of `jarvis.db`. Opens with WAL, loads `vec0.dylib`, runs migrations
`MemoryExtractionOrchestrator` (actor)	Bounded-channel + serial-drain extraction Task
`MemoryExtractionCoordinator`	AppDelegate-side coordinator that listens to `OrchestratorEvent.turnEnd`
`MemoryExtractor`	Calls Qwen 2.5-Coder via Ollama; emits ADD / UPDATE(supersedes:) / NOOP
`MemoryPrompts`	Prompt templates for the extractor
`HybridSearch` (actor)	FTS5 + vec0 RRF SQL; emits `ReplayEvent.memoryRetrieval` per fact
`OllamaEmbeddingClient`	`nomic-embed-text` 768-dim embeddings
`Fact` / `FactRef` / `ExtractionJob`	Plain-data types
`MemoryEvent`	Stream events — `factAdded`, `factUpdated`, `factForgotten`, `retrieval`
`SessionHistory`	Session-scoped recent-turn browse (TEXT-03; separate from hybrid search)
`MemoryReplaySink` (protocol)	Test seam over `Replay.ReplayLog`
`PriorFactsLookup`	Closure type for D-3 — supplies recent active facts to the extractor

Depends on

AgentCore, Replay, Logging. External: swift-log, system SQLite (with custom libsqlite3.dylib carrying SQLITE_ENABLE_LOAD_EXTENSION=1 once D-5 ships).

Used by

App/AppDelegate.installMemory, App/MCP/InProcessMemoryAdapters.swift (bridges to MCP SearchMemoryTool / ForgetFactTool).

Key invariants / contracts

MemoryStore is the only writer. All writes go through actor methods.
Bounded extraction channel. BoundedAsyncChannel<ExtractionJob>(capacity: 32, policy: .dropOldest). Producers (turnEnd) never block.
Single-consumer drain. One serial Task per orchestrator instance.
Single-emission grep gates. scripts/check-single-memory-mutated-emit.sh + check-single-memory-used-emit.sh. MemoryStore.recordRetrieval is the only memoryRetrieval emit site.
Embedding dim sourced from Constants.swift. scripts/check-embedding-dim-literal.sh forbids hand-typed 768.
Temporal validity preserved. UPDATE supersedes by setting valid_to on the prior fact + inserting a new one. No DELETE in the happy path.
D-3: priorFacts wiring. MemoryExtractionOrchestrator.process(_:) calls priorFactsLookup (default emptyPriorFactsLookup for back-compat); production wires MemoryStore.recentActiveFacts(limit: 50).
T-06-05-03 analog. HybridSearch does NOT log raw query text at debug level (P2-12 fix).

Tests

87 XCTest (19 skipped — vec0/Ollama gating). Includes the RememberBrutusEndToEndTests regression scenario (Track D-4) that proves extraction → store → search end-to-end with fakes.

Notable files

Sources/Memory/MemoryStore.swift — actor + SQLite + vec0 loader
Sources/Memory/MemoryExtractionOrchestrator.swift — bounded-channel extraction
Sources/Memory/HybridSearch.swift — FTS5 + vec0 RRF
Sources/Memory/MemoryExtractor.swift — Qwen extractor
Sources/Memory/MemoryQueries.swift — SQL definitions

3.5 KiB Raw Permalink Blame History