✨ The one-paragraph pitch

Most agent memory is written by an LLM on every turn (expensive, hallucination-prone), evaluated on question-answering (not actions), and assumes a single user. FERNme is built for the opposite world — agents that act for many people, in any domain (a sale, a booking, a resolved ticket, a completed lesson, a kept appointment — "outcome" is whatever the goal is). It starts where agents already act today — websites — and the same user-owned memory is designed to extend to desktop and mobile. Each user is a sparse, fuzzily-weighted node in a per-site graph; edges update by a Hebbian co-occurrence rule with zero LLM calls, retrieval is spreading activation, and the prompt-facing "card" stores only deviations from a population prior. The result: per-turn cost stays flat as a profile grows for years, the user can read and correct their own memory, and the same engine assembles — only with the user's consent — into a cross-site supernode they fully control.

🎯 Why FERNme (the strong points)

📊 Benchmarks

Honest scope: the numbers below are on synthetic or LLM-authored data, not real
users. They validate the mechanism and surface failures; a real-human pilot is the
pending next step. The Mem0 (LLM) head-to-head needs an API key and is not yet run.

On LLM-authored people (closest to real, agentic ingestion)

A sample of 16 of 92 third-person profiles (ChatGPT-authored), read as prose only and
remembered agentically, then scored against hidden answer keys:

(The "agent" here is an LLM reading prose, so these reflect agent + engine together — the
engine is solid; the extraction quality is the agent's.)

Cost, recall, and Pareto (synthetic, multi-seed)

Reproduce: python -m fernme.eval.cost_variance · ... quality · ... drift · ... context · ... ablation · ... pilot

Cost — per-turn memory tokens vs. profile size (5 seeds):

Recall quality — precision@5 vs. ground-truth preferences (5 seeds × 40 users):

The headline: FERNme is the only method strong everywhere. Frequency can't forget (fails drift); recency is noisy (fails static). FERNme's decay + spreading activation get both.

Cold-start ablation — population prior gives +0.06 precision@5 at turns 1–3, washing out by turn 10 (a real but modest, cold-start-only benefit).

Cost / quality Pareto (python -m fernme.eval.pareto) — measured FERNme recall &
tokens, modeled LLM nuance & price (assumptions in-file). Per 1,000 interactions:

FERNme+gated/offline sit on the efficient knee: ~80–90% of the LLM-ceiling quality
at 1–2 orders of magnitude less cost. (Modeled assumptions; shape is the point.)

Simulated outcome pilot — fake storefront, learn-from-behavior shoppers: +16% relative conversion lift over a popularity baseline; tied at visit 1 (cold start), pulling ahead as it learns, recovering through a mid-pilot taste drift.

🎚 Memory modes (one engine, a cost/quality dial)

FERNme ships one core with a deployment-level switch — FernService(memory_mode=...).
The default is free, key-less, and tested; LLM modes are opt-in and pluggable.

• A pluggable tagger (tagging.py) does the LLM work; you pass llm_fn, optionally
  constrained to a controlled vocabulary (the real consistency lever across models).
• The hot write path stays LLM-free in every mode; gated spends a call only when the
  deterministic mapping finds nothing, and svc.llm_calls counts every invocation for
  cost transparency.
• See the cost/quality Pareto above for where each mode lands. Honest note: the gated/
  offline quality is modeled until run against a real model — the wiring is tested
  here with a mock LLM, not validated for quality.

🧭 The 9 leapfrog dimensions (status)

FERNme's edge isn't the mechanism (that's now a crowded 2026 category) — it's competing
on dimensions single-user, vendor-owned, recall-optimized systems structurally can't.

These are deliberately the things HippoGraph et al. can't follow: they're single-user
(no collective priors), vendor-owned (no user-owned protocol), and recall-optimized
(no outcome loop). Built in honest, tested slices — research-dependent ones are marked.

🏗 Architecture

flowchart TD
    V[Visitor on a website] -->|prompt + action| API[FERNme Service]
    API --> CONSENT{consent?}
    CONSENT -->|no| STOP[blocked]
    CONSENT -->|yes| ENGINE
    subgraph ENGINE[Engine - no LLM in the write path]
      W[Hebbian write + decay] --> G[(Per-site preference graph<br/>fuzzy 0-9 edges)]
      G --> R[Spreading-activation retrieval]
      R --> CARD[Token-minimal card ~25 tok]
      PRIOR[Population prior<br/>differential encoding] --> R
    end
    CARD --> AGENT[Agent: recommend / act]
    G --> CAB[(Cabinet: raw event log)]
    API --> STORE[(SQLite or Postgres<br/>multi-tenant)]
    API --> GLASS[🪟 Glass-box editor]
    API -.user signs in.-> SUPER[User-owned Supernode<br/>cross-site, default-deny]

🧠 How FERNme works (visual walkthrough)

Why FERNme — adaptive local memory instead of expensive RAG/vector retrieval in the loop.

What makes it different — near-zero-LLM, deterministic-first, Hebbian, fuzzy, memory cards, action-aware, user-owned.

How memory grows — new event → connect → strengthen → decay → update the card (Hebbian learning).

The fuzzy Hebbian graph — sparse, weighted (0–9) edges; nodes for users, preferences, topics, goals.

The LLM gate — an exception, not the default. Most events are handled deterministically; the LLM is a rare fallback when uncertain.

The memory card — a bounded, interpretable, token-minimal summary of what matters.

Action-aware learning — good outcomes strengthen connections, bad outcomes weaken them.

The road ahead — today's local memory; tomorrow's recursive organization and user-owned supernode (roadmap, not yet built).

Full architecture: ingestion bridge → namespaced vocabulary → fuzzy Hebbian graph → memory card → agent, with the LLM gate only when uncertain.

🚀 Quickstart

pip install -e ".[dev,api]"

python run_demo.py                      # cold-start → learning → glass-box edit
python supernode_demo.py                # one person, three sites, one owned profile
pytest -q                               # 91 tests (engine, store, supernode, safety, auth…)

# experiments
python -m fernme.eval.drift               # FERNme beats a frequency counter when tastes change
python -m fernme.eval.pilot               # +16% simulated conversion lift

# run it live
FERNME_API_KEY=secret uvicorn fernme.api.rest:app --port 8077   # REST API (docs at /docs)
open http://localhost:8077/ui                               # glass-box memory editor
open http://localhost:8077/graph                            # your memory as a graph — focus by site / PC / phone
python -m fernme.api.mcp_server                               # MCP server for agents/Claude

🗄 Storage: defaults to ~/.fernme/fernme.db (SQLite). For production use PostgresStore — same interface, tested against a real Postgres 16. Keep SQLite off cloud-synced folders.

🧱 What's inside

• Engine — saturating Hebbian write (no LLM), ACT-R decay, spreading activation, token-minimal card.
• Population prior — IDF cold-start; differential (deviation-only) storage is
  enforced by an explicit prune_to_prior pass (redundant edges read through to the prior).
• Stores — SQLiteStore (zero-setup) and PostgresStore (tested vs real PG 16), one interface.
• Ingestion bridge — a per-site catalog (item_id->tags) plus a controlled,
  namespaced vocabulary (vocabulary.py) that canonicalizes every tag (catalog,
  free text, or LLM) to one form (pref:, topic:, goal:, context:) so the same
  concept never drifts across months. Deterministic by default; gated-LLM only for
  novel free text. This is the product-critical layer — and the foundation a future
  recursive/region organization would group on.
• The Cabinet — append-only event log with recall() for specific facts.
• Supernode (supernode.py + auth.py) — user-owned cross-site profile, built by sign-in (verified token → opaque person id), default-deny scoped views, sensitive categories walled off.
• Proactive triggers — due-to-reorder + fading-favorite nudges.
• Safety — event tags treated as untrusted data: injection-pattern dropping, size/value caps.
• Interfaces — REST (/observe /card /recall /edit /export /delete /triggers …) + MCP tools + a glass-box web UI (editor at /ui, cross-surface memory graph at /graph — one memory, focusable by site / PC / phone).
• Governance — consent-gated everywhere; export & right-to-be-forgotten built in.

🔬 How FERNme compares

FERNme is a different category from conversational memories — it's a per-user preference graph evaluated by actions, not a QA memory. Don't benchmark it on LoCoMo; that's the wrong axis.

Leads on: write cost, interpretability, per-site user-ownership/consent. Honestly behind on: nuanced/causal preferences (LLM extraction wins), benchmark credibility, ecosystem & distribution.

⚖️ Honest status

✅ Done & tested (91 tests): engine, SQLite + real-Postgres stores, supernode + sign-in, triggers, safety, REST/MCP, glass-box UI + memory-graph view, and the full results suite above.

🚧 Still open (genuinely needs the outside world):

• A real-human per-site pilot — only live users close the loop a simulator can't.
• The Mem0 (LLM) head-to-head — harness wired; run locally with OPENAI_API_KEY.
• Embeddings for context→attribute matching; offline LLM catalog enrichment for messy inputs.
• Desktop & mobile surfaces — the engine is substrate-agnostic; web ingestion ships today, desktop/mobile adapters are on the roadmap. The user-owned supernode is the bridge that assembles them, with consent, into one cross-surface profile.

Every claim above is backed by a test or a reproducible experiment. Where a result is simulated, it says so — a simulator proves the mechanism, not real-world behavior.

📁 Layout

fernme/
  core/      graph types · fuzzy 0–9 edges · event record
  write/     event→attr mapping (no LLM) · Hebbian update · decay
  retrieve/  base-level + spreading activation · token-minimal card
  prior/     population prior · differential encoding · IDF cold-start
  store/     sqlite_store · postgres_store (one interface)
  supernode.py · auth.py · triggers.py · safety.py · service.py
  api/       rest.py (FastAPI) · mcp_server.py · web/glassbox.html · web/graph.html
  eval/      simulator · cost · quality · drift · context · ablation · pilot
tests/       91 tests   ·   *_demo.py walkthroughs

📜 License & citation

Apache-2.0, © 2026 Acquilab Inc. — see LICENSE and NOTICE. Security notes in SECURITY.md; the name is a working codename (see NAMING.md).
If you use FERNme in research, please cite it via CITATION.cff.