@x-otto/memory 0.0.1-alpha.2 → 0.0.1-alpha.4

package/README.md

@@ -1,6 +1,6 @@
 # @x-otto/memory
 
-Agent working memory pipeline: LLM-driven compaction, LLM-free pruning, archive persistence, multi-source AGENTS.md memory, writable cross-session auto-memory, operational learning, and workspace file-state snapshots.
+Agent working memory pipeline: LLM-driven compaction, LLM-free pruning, multi-source AGENTS.md memory, writable cross-session auto-memory, operational learning, and workspace file-state snapshots.
 
 ## Install
 
@@ -15,9 +15,8 @@ import { MemoryManager, OperationalLearningStore, FileStateManager } from '@x-ot
 
 // Pipeline: prune → compaction → archive
 const memory = new MemoryManager({
-  workspaceDir: process.cwd(),
-  model: 'claude-sonnet-4-5',
-  provider: myProvider,
+  summarize: async (prompt, opts) => myLLM.complete(prompt, opts),
+  model: { contextWindow: 200_000, maxOutput: 8_192 },
 })
 const result = await memory.process(messages, sessionId)
 // Returns { messages, summary, archivePath, pruned, compacted }
@@ -33,7 +32,7 @@ await lessons.save({ tags: ['testing'], trigger: 'flaky test', insight: 'reset s
 // File state snapshot
 const fsm = new FileStateManager()
 const snapshot = await fsm.capture({ workspaceDir: '.' })
-// snapshot → { tree, recentFiles: { created, modified, deleted } }
+// snapshot → { directoryTree, modifiedFiles: { created, modified, deleted }, findings }
 ```
 
 ## Pipeline: prune → compaction → archive
@@ -43,23 +42,24 @@ const snapshot = await fsm.capture({ workspaceDir: '.' })
 - Triggered when estimated tokens exceed `prune.trigger` threshold
 - Protection window: last N messages (by token count) are always kept
 - `tool_result` content outside protection → `[output pruned — N tokens]`
-- `tool_call` arguments for write tools (write/edit/apply_patch) truncated beyond `truncateMaxLength`
+- `tool_call` arguments for write tools (write/edit) truncated beyond `truncateMaxLength`
 - Minimum gain gate: rolls back if net savings < `minimum` tokens
 
-### 2. Compaction — LLM-driven summary (`compaction.ts`)
+### 2. Compaction — LLM-driven summary (`compaction-backend.ts`)
 
 - `findCutPoint`: keep recent tokens, align to user/assistant boundary, detect split-turn
 - Separates messages-to-summarize / preserved / turn-prefix region
 - Extracts file operations (read/modified paths) from tool_results
-- Calls injected `summarize(system, messages, opts)` with structured prompt (Goal / Constraints / Progress / Key Decisions / Next Steps / File Operations / Critical Context)
+- Calls injected `summarize(prompt, opts)` with structured prompt (Goal / Constraints / Progress / Key Decisions / Next Steps / File Operations / Critical Context)
 - Iterative: previous summary + new messages → `UPDATE_SUMMARIZATION_PROMPT`
 - Split turn: generates additional turn-prefix summary via `TURN_PREFIX_SUMMARIZATION_PROMPT`
 
-### 3. Archive — persist compaction output (`archive.ts`)
+### 3. Archive — session-derived view (`archive-source.ts`)
 
-- Formats compressed messages + summary as Markdown (single messages >2000 chars truncated)
-- Backends: `InMemoryArchiveStorage` (default), `PersistenceBackedArchiveStorage` (file/HTTP via `@x-otto/persistence`)
-- Factory: `createArchiveStorage(options)` — file default `$OTTO_HOME/agent/archives`
+- Archive is a session-derived view (compaction boundaries reconstructed from session entries on demand), not independent persistence
+- `InMemoryArchiveStorage` retained as V-form (headless, no session tree) fallback
+- `ArchiveSource` interface unifies both implementations; `MemoryManager` has no form-branching
+- Backend: `InMemoryArchiveStorage` (default; the former `PersistenceBackedArchiveStorage` / `createArchiveStorage` file/HTTP stack was deleted — archive is now a session-derived view, not independent persistence)
 
 ## Persistent Memory (`persistent-memory.ts`)
 
@@ -97,7 +97,7 @@ CJK-aware classification heuristic (not `length/4`):
 - CJK: 1 token/char, ASCII/symbols: 0.25–0.5/char → conservatively high (triggers early rather than overflow)
 - `estimateMessageTokens`: content blocks (text/thinking/tool_call), images ~2000 tokens constant, + role overhead
 - `estimateContextTokens`: hybrid — last assistant's usage as baseline, estimate only trailing tail
-- Exports `messageToText` and re-exports `getTokensFromUsage` from `@x-otto/ai`
+- Exports `messageToText`
 
 ## Operational Learning (`operational-learning.ts`)
 
@@ -125,28 +125,37 @@ Read-only workspace snapshot for agent context:
 ```
 src/
   types.ts                  # Config types, MemoryStore, ArchiveStorage, ManagerConfig
-  memory-manager.ts         # Pipeline coordinator + persistent memory facade
+  memory-manager.ts         # Pipeline coordinator + persistent memory facade + trigger orchestration
   prune.ts                  # No-LLM pruning (window, tool_result truncation, gain gate)
-  compaction.ts             # Cut point, LLM summary, split-turn, file ops extraction
-  archive.ts                # InMemoryArchiveStorage + formatArchive + createArchiveStorage
+  compaction.ts             # Pure functions: findCutPoint / isSummaryMessage / extractFileOps / formatFileOps
+  compaction-backend.ts     # CompactionBackend: compact/prepare/isEligible (strategy-execution separation)
+  trigger-policies.ts       # TriggerPolicy interface + TokenPressure/RealInput/Residency/Prune policies
+  coverage-governor.ts      # Per-session coverage boost state (instance-owned)
+  archive-source.ts        # ArchiveSource interface + SessionEntries/InMemory implementations
+  compaction-truncation.ts  # Summary-input formatting & truncation primitives
+  memory-injection.ts       # <agent_memory> injection: budget accounting + index folding
+  archive.ts                # InMemoryArchiveStorage + formatArchive
   persistent-memory.ts      # AGENTS.md multi-source + FileSystemMemoryStore / InMemoryMemoryStore
   http-memory-store.ts      # Remote HTTP memory store
   auto-memory.ts            # Cross-session progressive-disclosure memory
   auto-extract.ts           # Auto-memory candidate extraction
   agents-discovery.ts       # AGENTS.md path discovery
   memory-extractor.ts       # Derive persistable memory entries from session
+  evolution-signal-store.ts # Evolution-observation unified signal exit (append-only)
+  signal-log.ts             # SignalLog persistence (AppendLog JSONL domain wrapper)
+  overlay-memory-store.ts   # Shadow-mode MemoryStore overlay (reads-through, writes in-memory)
   token-estimator.ts        # CJK-aware token estimation + usage-hybrid context
   defaults.ts               # computeMemoryDefaults / resolveContextSize
   operational-learning.ts   # Lessons store (CRUD + weighted search + atomic persistence)
   file-state-snapshot.ts    # Workspace read-only snapshot
-  prompts.ts                # Summary prompts + memory/archive injection builders
-  constants.ts              # Thresholds, paths
+  prompts.ts                # Summary prompts + archive reference builders
+  constants.ts              # Thresholds, paths, conflict ring size
   index.ts                  # Barrel exports
 ```
 
 ## Dependencies
 
-- Internal: `@x-otto/ai` (Message types, getTokensFromUsage), `@x-otto/persistence`, `@x-otto/shared`, `@x-otto/env` (thresholds, tool name constants)
+- Internal: `@x-otto/interchange` (Message types), `@x-otto/persistence`, `@x-otto/shared`, `@x-otto/env` (thresholds, tool name constants)
 - External: `js-tiktoken`
 - LLM access: via injected `summarize` callback (not direct)