FindingMemo

Finding Memo — the hard part of memory isn't storage, it's finding (retrieval). Codename Factor-X.

A brain-inspired associative long-term memory layer for an LLM agent. The agent keeps its own reasoning loop; FindingMemo is a subordinate, grounded memory backend it writes to and recalls from. Started as design notes (Nam × Claude, 2026-06); the automatic (implicit) tier is now implemented on dev.

Thesis

An LLM is natively an imagination/generation engine but lacks grounded long-term memory. FindingMemo supplies it as a labeled property graph with embeddings on nodes and learned weights on nodes and edges (the associative-memory shape), recalled by embedding-match → personalized-PageRank spreading activation, surfaced as a fixed-budget context block rendered per turn. Human-readable, git-versioned, propose-only facts stay the canonical layer; the graph/vector store is a derived, disposable index over it.

What works today (automatic tier)

The pipeline capture → embed → recall → sleep, over an embedded KuzuDB graph store with local fastembed embeddings — no external services.

events.jsonl ──ingest──▶ embed (fastembed) ──▶ KuzuDB graph
                                                   │
   query ──embed──▶ seed (vector match) ──▶ personalized PageRank ──▶ render_block (token-budgeted)
                                                   │
                                       reinforce (Hebbian, on recall)
                                                   │
                                    consolidate (sleep-pass: decay / SHY / prune / demote)

• Store (src/store/schema.ts): nodes Memory (embedding, weight, confidence, provenance, hot/cold tier) and Entity; edges ASSOC (weighted association), MENTIONS (Memory→Entity), JUSTIFIED_BY (provenance / TMS), ROLE.
• Recall (src/recall/): seedFromVector (embedding match) → personalizedPageRank spreading activation → renderBlock (fixed token budget). Reinforces the recalled set on use unless --no-reinforce.
• Dynamics (src/dynamics/): Hebbian reinforce (co-activation pairs strengthen) + a decay / SHY sleep-pass that prunes dead edges and demotes weak nodes to the cold tier.
• BE daemon / warm core (src/server/): a small HTTP server so host hooks can recall over HTTP without paying cold-start each turn. KuzuDB is single-writer — when the daemon holds the store it OWNS it, and db-touching CLI commands automatically route through it. Never open the store from two processes at once.
• Live 3D graph view (src/server/viz.ts): an interactive 3d-force-graph / Three.js view at /viz with node/edge + weight-range filters and SSE live refresh (camera-preserving) as the store mutates.

Quickstart

npm install                 # pulls kuzu + fastembed (first embed run downloads the model)
npm run build               # tsc → dist/   (or run everything via tsx below, no build)

npx memo schema             # create the store schema (default ./data/memo)
npx memo ingest             # capture ./fixtures/events.jsonl → embed → graph
npx memo recall "<query>"   # semantic + PPR recall; prints the render_block
npx memo viz                # open the live 3D graph (starts the daemon if needed)

During development use npm run memo -- <command> (runs src/cli/memo.ts via tsx, no build step).

CLI (memo)

schema                  create / upgrade the store schema
ingest [events.jsonl]   capture events → embed → graph   (default ./fixtures/events.jsonl)
recall "<query>"        semantic + PPR recall; prints render_block (reinforces on use)
consolidate             sleep-pass: decay/SHY weights, prune dead edges, demote weak → cold
serve                   run the BE server in the FOREGROUND (warm core; hooks call it over HTTP)
start | stop | restart  manage the BE server as a background daemon (PID file next to the store)
viz                     open the live graph view (starts the daemon if needed)
status                  store stats (nodes / edges / tiers) + server state
install | doctor | eval (not implemented yet)

-v, --verbose      recall: show PPR ranking · ingest: list events
    --no-reinforce recall as a pure read (no Hebbian strengthening)
    --db <path>    store path        (default ./data/memo, env MEMO_DB)
    --port <n>     server port        (default 3737, env MEMO_PORT)
    --interval <s> viz refresh seconds (default 30)

HTTP API (BE daemon, 127.0.0.1:3737)

For hook-driven recall from a host harness:

POST /recall      {query, budget?, reinforce?}  → {block, tokens, nodes[]}
POST /capture     {events[]}                     → ingest stats
POST /consolidate {opts?}                         → sleep-pass stats
GET  /health · GET /status · GET /graph
GET  /events                                      SSE — pushes "update" on every store mutation
GET  / | /viz                                     the live 3D graph HTML

Library

Also consumable as a library (findingmemo, main → dist/index.js):

import { openStore, ensureSchema, ingest, recallRanked, renderBlock,
         reinforce, consolidate, startDaemon } from 'findingmemo';

Exports the full pipeline: store (openStore/ensureSchema/queryAll), embedTexts/embedQuery, ingest, loadGraph/seedFromVector/recallRanked/renderBlock, personalizedPageRank, reinforce/consolidate, startServer/startDaemon, stampProvenance.

Design background (vision → architecture)

The built tier realizes these notes; keep them for the why + the honest caveats. "X" is the codename (Factor-X); FindingMemo is the project/package.

• 00-cognitive-foundations.md — imagination = generation, perception vs imagination (reality-monitor), the two memory taxonomies, arbitration / dual-system.
• 01-memory-systems-survey.md — Letta (MemGPT) vs Mem0/Mem0g; how they'd wire into a host; the cost-vs-accuracy reality.
• 02-X-architecture.md — the concrete design: weighted property graph + vectors, recall (embedding → personalized PageRank), the always-injected context block, episodic anchoring, epistemic/TMS provenance, active forgetting, memory dynamics.
• 03-cognitive-faculties.md — brain faculties as design dimensions; motivation as an EVC controller → dynamic model-cost routing.
• 04-self-monitoring-and-confidence.md — the cognitive-control layer: confidence ESTIMATE vs THRESHOLD, the answer-gate, carefulness = permission MODE.
• 05-packaging-and-deploy.md — how it ships: the Playwright model (npm i findingmemo + npx memo …), lib + MCP + scaffolder, the invasive-init caveat.
• 06-memory-roles-and-ogden.md — one store, two access modes (automatic substrate vs deliberate curator subagent); Ogden re-homed here (agents/ogden.md) from Neurealistic/claustrum; design/automatic-layer.md specs the implemented tier.

Status

• ✅ Automatic tier: capture / embed / recall / reinforce / consolidate, BE daemon, live viz.
• ⬜ Deliberate tier: the Ogden curator subagent (agents/ogden.md) — one store, two access modes.
• ⬜ memo install | doctor | eval — scaffolder + health-check + retrieval eval (stubbed).
• ⬜ Packaging as the npm i findingmemo + npx memo init bolt-in per 05-packaging-and-deploy.md.

Layout

src/
├── cli/memo.ts         # the `memo` CLI
├── ingest/ingest.ts    # capture → embed → graph
├── embed/embed.ts      # fastembed local embeddings
├── recall/{index,ppr}.ts   # seed → personalized PageRank → render_block
├── dynamics/index.ts   # Hebbian reinforce + decay/SHY sleep-pass
├── store/schema.ts     # KuzuDB schema (Memory/Entity + ASSOC/MENTIONS/JUSTIFIED_BY/ROLE)
├── server/{server,daemon,viz}.ts   # warm-core HTTP daemon + live 3D graph
├── index.ts · types.ts # library entry + provenance/RawEvent types
00-…06-…md · design/    # design notes (background)
agents/ogden.md         # the deliberate-tier curator (pending)

Private (Neurealistic/FindingMemo-dev); a public release follows later.