mnemosyne-core — Architecture

The @mnemosyne/core package is the tiered memory system core for the Mnemose agent (domain-agnostic). It provides the memory service, domain modules, and the memory-tool surface consulted by the IAM escalation reviewer and the agent loop.

Responsibilities

Define the tiered memory model (core / operational / persistent KV + vector tiers)
Provide MemoryService orchestration for storing, searching, and recalling memories
Provide the memory-tool MCP surface the agent loop uses to consult and update memory
Expose a MnemosyneMemorySystem facade and ReviewerMemory subset for the escalation reviewer

Key Components

File / Dir	Role
`src/library.ts`	Public API barrel — exports core types, services, domains
`src/services/MemoryService.ts`	Service-layer orchestration for memory read/write
`src/core/`	Core architecture types + base classes
`src/domains/`	Domain layer (memory domain)
`src/modules/core-memory.ts`	Volatile in-process memory tier (write-through persistence staged for follow-up)
`src/modules/persistent-tier-integration.ts`	Persistent KV + vector tier integration + health checks
`src/multi-tier-memory.ts`	Multi-tier memory coordinator
`src/memory-tool.ts`	MCP tool surface for memory search/recall consulted by the agent loop
`src/migrations/`	Persistence schema migrations

Dependencies

@modelcontextprotocol/sdk (for the memory-tool surface)
@mnemosyne/sqlite (optional persistent tier, see that package)

Data Flow

agent loop / escalation reviewer
  ↓ MemoryService.search(query) → MemorySearchResult[]
  ↓ MemoryService.store(item)
  ↓ core-memory tier (volatile) → persistent-tier-integration (KV + vector)
  ↓ memory-tool MCP surface (agent consults/recalls)

Status Notes

Some persistence stubs remain (volatile Map core-memory tier, fabricated health checks) — see FINDINGS M12. The decisioning logic in services/agent/src/escalation-reviewer.ts consults a ReviewerMemory subset of this package; when the full Mnemosyne stack is unavailable the reviewer falls back to an in-process decision log so the engine is testable.