Skip to content

refactor: introduce Memory Engine module as deep facade over memory pipeline #251

@cniska

Description

@cniska

Problem

The glossary names Memory Engine as a top-level concept, but no module embodies it. Understanding how memories flow — recall → context injection → distill-at-finalize — requires reading across 7 files: `memory-ops.ts`, `memory-store.ts`, `memory-distiller.ts`, `memory-toolkit.ts`, `memory-embedding.ts`, `agent-reminders.ts`, and `lifecycle-generate.ts`.

`memory-ops.ts` provides partial access (raw store ops: `addMemory`, `listMemories`, `removeMemory`) but doesn't cover recall, distillation, or embedding. There is no shared facade for the full per-turn memory lifecycle. Deleting `memory-ops.ts` doesn't remove complexity — it reappears across 12 callers.

Proposed solution

Introduce `memory-engine.ts` as a deep module that owns the full per-turn memory lifecycle:

  • Recall (ranked by hybrid TF-IDF + embedding similarity)
  • Toolkit binding (`memory-search`, `memory-add`, `memory-remove` tools)
  • Distill-at-finalize (post-turn observation commit)

Lifecycle phases get one interface; the 7-file implementation disappears behind it.

Benefits

  • Locality — memory pipeline is testable as a unit against one interface
  • Leverage — lifecycle phases don't need to know whether memory is embedded, TF-IDF-ranked, or distilled via tool call
  • Navigability — "Memory Engine" in the glossary maps to a real module

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions