Architecture

​

The single-owner model

​

Packages

​

The engine contract

interface MemoryEngine {
  save(input): Promise<SaveResult>;
  recall(query, opts?): Promise<Memory[]>;
  memories(): Promise<Memory[]>;          // browse (recall is for querying)
  update(input): Promise<UpdateResult>;   // new version of a belief
  history(memoryId): Promise<Memory[]>;   // the full version chain
  index(): Promise<IndexResult>;          // entity extraction → graph edges
  graph(): Promise<Graph>;
  conflicts() / resolveConflict() / revertConflict();
  contextAdd() / contextList() / contextChunks() / contextRemove();
}

​

Storage tiers

• PgliteAdapter: the embedded tier. What the daemon uses. Zero setup, data in a folder.
• PgAdapter: a real Postgres server over the wire (Docker, Supabase, any managed Postgres with pgvector), pooled. Selected with MEMLOOM_PG_URL in config.env; see Self-hosting.

​

Design rules worth knowing

• All config is injected. Core never reads process.env or global state. The daemon is the only place environment/config is read, then everything is passed in as constructor arguments. This is why the whole engine is testable without a network.
• The edge table has no foreign keys. memory_edges links memories, entities, and context chunks in one table. Those are different node tables, so FKs are impossible by design. The trade: cascade deletes can’t clean edges, so every chunk/memory removal path deletes its edges explicitly.
• Nothing is destroyed. Superseded memories go status = 'stale', edges deactivate (active = false) rather than being deleted. This is what makes conflict resolution and versioning reversible.
• Migrations are ordered and idempotent. Memloom.init() runs pending migrations, then verifies the store’s embedding fingerprint: a store embedded with one model refuses to open under another, because mixed vector spaces make similarity silently meaningless.

​

Data layout

~/.memloom/            (override with MEMLOOM_HOME)
├── config.env         settings the daemon reads at startup
└── data/              the Postgres data directory, your memory. Copy it = backup.