🌿 FERNme

Fuzzy-Edged Recall Network

Agent personalization memory that models the user, not the transcript.

A user-owned personalization memory layer for AI agents: zero-LLM deterministic core, with optional low-cost human-approved enrichment. It turns consented interactions into an inspectable model of each person's preferences, habits, communication style, and constraints, staying token-flat as it grows while people can see, edit, delete, and own what agents use to personalize.

Cheap to write · flat to read · interpretable by design · owned by the user

fernme.dev

✨ 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. It starts where agents already act today, websites, and builds a user-owned personalization model the person can inspect and control. Each user is a sparse, fuzzily-weighted node in a per-site graph; the graph also supports opt-in typed entities with labeled, Hebbian-weighted relations while the deterministic write/recall core stays at zero LLM calls. Optional propose-only enrichment can add connection suggestions powered by the agent you already use or a model you choose; nothing lands in memory truth until a human accepts it. Retrieval is spreading activation, and the prompt-facing card stores only deviations from a population prior.

What it is / is not

🎯 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. Entity-layer validation includes synthetic acceptance fixtures, the entity micro-eval, and one scoped maintainer-copy check; broader real-profile benchmarks are still pending.

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 · ... retention · ... ablation · ... pilot · ... entities

Unified harness: python -m fernme.eval.harness --seeds 6 --json reports/eval_harness.json

Canonicalization queue: python -m fernme.eval.canonicalization --seeds 6 --json reports/canonicalization.json

Propose-only enrichment: python -m fernme.eval.enrichment --seeds 6 --json reports/enrichment.json

Unified Phase 8.1 harness - synthetic hidden-answer-key scenarios for static, abrupt drift, gradual drift, staleness, contextual, fragmented-entity, and outcome regimes. Same events/probes for every method; BM25 reads Cabinet event text with a pure-Python scorer; all methods in this table make no model calls. Outcome rows include action quality; non-FERN baselines do not have an outcome feedback mechanism.

Read this as a quality gate, not a victory lap: BM25 wins when query text directly matches Cabinet prose but spends far more context tokens; recency wins the deliberately abrupt drift fixture; frequency fails staleness; entity flags matter on fragmented identity; and only FERNme exercises the outcome loop. FERNme stays compact and zero-call, but it does not dominate every synthetic regime.

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

Older focused recall modules remain regression checks, but the unified harness above is the README source of truth for cross-method quality claims.

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).

Typed-entity A2 micro-eval (python -m fernme.eval.entities) — synthetic, fictional alias-fragmentation fixture. It reports the rank of a fragmented person entity with entity_aggregation off vs. on. The entity layer also has one scoped maintainer-copy check listed in Honest status; treat that as n=1 evidence, not a general real-profile benchmark.

Suggest-and-approve canonicalization eval (python -m fernme.eval.canonicalization --seeds 6 --json reports/canonicalization.json) - synthetic, fictional fragmented-alias fixture with planted duplicate aliases. The queue is propose-only: no candidate changes memory truth unless a human accepts it.

Propose-only enrichment eval (python -m fernme.eval.enrichment --seeds 6 --json reports/enrichment.json) - synthetic, fictional relation-link fixture with a mock proposal source. OFF is inert; ON reads Cabinet text in a batch, validates proposals, and enqueues suggestions only.

Agent-driven proposals spend the caller agent's tokens outside FERNme and leave svc.llm_calls at 0. This eval is a harness wiring check, not a real-model quality claim. Cost / quality status for enrichment - the old gated/offline Pareto table was modeled before Phase 12. The current backed number is the synthetic propose-only enrichment eval above. Real-model quality and cost are deliberately not claimed until an owner-run model eval exists. Simulated outcome pilot — fake storefront, learn-from-behavior shoppers: +17% 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 and enrichment

FERNme ships one deterministic memory core with a deployment-level switch: FernService(memory_mode=...). Every hot write and recall stays model-free in every mode. Optional enrichment is a separate, default-off proposal tier.

• propose_relation(...) and propose_entity_link(...) enqueue suggestions into the existing human review queue. Accepting applies through entity_relate or entity_link_alias; rejecting sticks.
• Model or agent output is untrusted data. Relation vocabulary, entity kind checks, same-surname/low-confidence rules, and injection filters run before anything is enqueued.
• The old gated/offline mode names remain for compatibility, but they do not write model-derived truth during observe. consolidate() is now a compatibility wrapper around propose-only enrichment.
• See the synthetic enrichment eval above for the current measured ON/OFF delta with a mock proposal source. Real-model numbers are owner-run only.

🧭 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 - zero-LLM write/recall core]
      W[Hebbian write + decay] --> G[(Per-site preference graph<br/>fuzzy 0-9 edges)]
      W --> E[(Entity tables<br/>entities, aliases, fields, relations)]
      E -->|opt-in alias aggregation| R
      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.	Core principles - zero-LLM deterministic core, optional human-approved enrichment, Hebbian, fuzzy, memory cards, action-aware, user-owned.
How memory grows — new event → connect → strengthen → decay → update the card.	Fuzzy Hebbian graph — sparse, weighted (0–9) edges for users, preferences, topics, and goals.
Propose-only enrichment - agent/model suggestions go to review; nothing auto-writes truth.	Memory card - bounded, interpretable, token-minimal context for the agent.
Action-aware learning - good outcomes strengthen connections, bad outcomes weaken them.	Architecture - ingestion bridge -> vocabulary -> fuzzy graph -> memory card -> agent, with optional proposal enrichment off the hot path.

Local graph UI demo: FERNme now ships a bundled React SPA at /ui/graph instead of the old single-file HTML graph. The screenshot below is generated only from the checked-in synthetic Elena fixture, not from a private database. The UI has source-owned assets, remembered site/user defaults, canonical entity-kind filters, category filters, known-only filtering, search/focus, relation hover labels, animated focused links, 2D plus optional spatial mode, and a flip-in selected tag/entity card with evidence and confidence details.

Elena's memory (fictional demo) — local SPA graph UI with canonical entity filters, focused relation animation, and an inspectable project card. Every visible node stays synthetic and every relation remains explainable.

🚀 Quickstart

pip install <path-to>/fernmark-0.4.0a9-py3-none-any.whl
pip install -e ".[dev,api,fernmark]"

python run_demo.py                      # cold-start → learning → glass-box edit
python supernode_demo.py                # one person, three sites, one owned profile
python -m pytest tests -q               # 283 passing, 2 skipped with FERNmark installed

# experiments
python -m fernme.eval.drift               # FERNme beats a frequency counter when tastes change
python -m fernme.eval.retention           # permanent facts persist while stale volatile facts fade
python -m fernme.eval.pilot               # +17% simulated conversion lift

# run it live
FERNME_API_KEY=secret uvicorn fernme.api.rest:app --port 8077   # REST API (docs at /docs)
fernme-ui --site demo --user elena --port 8077 --no-open    # local SPA + graph UI
open http://localhost:8077/ui/graph                         # graph, review queue, editor, feed, health
open http://localhost:8077/graph                            # legacy redirect to /ui/graph
fernme-mcp --print-db-path                                   # show the shared SQLite DB path
fernme-mcp                                                   # MCP server for agents/Codex/Claude
python -m fernme.import_obsidian ./vault --site demo --user elena --dry-run
python -m fernme.import_fernmark ./document.fernmark.json --site demo --user elena --dry-run

🗄 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.

MCP and plugin packaging

Install and find your database:

pip install fernme
fernme-mcp --print-db-path
fernme-mcp

The default install includes the MCP server. On first use, FERNme creates one SQLite database at ~/.fernme/fernme.db unless FERNME_DB points somewhere else. fernme-mcp --print-db-path prints the resolved path to stdout and exits; normal MCP startup logs the path to stderr so stdout remains clean for JSON-RPC. Set that same FERNME_DB in Codex/Cowork MCP config env, the CLI importer, and the UI process when you want the agent and graph to use the same memory. Optional FERNME_SITE and FERNME_USER provide local defaults for tools that omit them. For the graph UI dependencies, install pip install "fernme[ui]".

Bundled local plugin manifests live under packaging/:

codex plugin marketplace add ./packaging/codex
claude plugin marketplace add ./packaging/claude

The Codex package includes .codex-plugin/plugin.json, .mcp.json, and a fernme-memory skill. The Claude Code/Cowork package follows the current .claude-plugin/plugin.json plus .mcp.json layout, and the repo root includes .claude-plugin/marketplace.json for GitHub marketplace discovery.

For Cowork after the owner pushes the repo: Customize > Plugins > "+" > Add marketplace from GitHub > enter the repo URL > Install fernme-memory > authorize the MCP server. For Claude Code CLI: /plugin marketplace add mirkofr/FERNme, then /plugin install fernme-memory@fernme-local.

The shipped MCP configs run:

uvx --with "fernmark @ git+https://github.com/mirkofr/FERNmark.git@23e16ea5b01f4ce77fee81b5bf4f7e0d87d77bae" --from "fernme[mcp] @ git+https://github.com/mirkofr/[email protected]" fernme-mcp

The bundled plugin enables managed documents. It can preview an explicitly named raw FERNmark-supported file or existing envelope using import_document(..., confirm=false) and returns only redacted metadata. After the user agrees, confirm=true writes UTF-8 Markdown plus a canonical envelope below FERNME_VAULT, stores a durable catalog row, and returns only relative pointers. Semantic tags remain proposals until a human accepts them.

No PyPI publish is required for the plugin route. The plugin is pinned to the reproducible release ref v0.4.0b2, so external testers get the same server build. The owner must push main and create plus push the v0.4.0b2 tag on a public or otherwise reachable repo before testers can fetch it. PyPI publish is an owner action triggered by that v* tag after trusted publishing is configured. See docs/mcp.md for local development alternatives.

Import your Obsidian vault

FERNme can import a local Obsidian vault deterministically:

python -m fernme.import_obsidian ./vault --site demo --user elena --dry-run
python -m fernme.import_obsidian ./vault --site demo --user elena --max-notes 100

The importer requires consent, preserves Markdown note bodies in the Cabinet as data, maps simple frontmatter tags through the existing vocabulary, extracts structured fields such as email and ISO dates into event payloads, and queues wikilink or alias candidates for human review. It never auto-applies entity truth. Through MCP, agents call import_obsidian(site, user, path, ...); the path is on the MCP server machine and the returned summary is counts-only.

Managed document evidence (FERNmark)

FERNme can convert raw supported files locally or ingest FERNmark's validated schema-v1 envelope without adding an LLM call. The optional dependency is pinned to an immutable public Git commit. Use a placeholder path in shared instructions, never a machine-specific path:

pip install "fernme[fernmark]"
set FERNME_MANAGED_DOCUMENTS=true
set FERNME_VAULT=<vault-root>

The engine flag is default-off; the bundled plugin enables it. Preview performs conversion and validation in memory with zero persistent writes. Confirmation stores full Markdown as Cabinet evidence and catalog metadata separately from the normal hot graph, and writes through the same single CapturePipeline -> service.observe() path as every other import, so native identity tags (doc:, mime:, quality:, plus origin/vault/status/title facts) always reach the graph. recall_documents returns a bounded metadata overlay with relative pointers and continuation (with a hint naming import_document on an empty catalog), while normal recall_card and its assoc_floor remain unchanged. Archive, supersede, pin, authority, and selective forget operations are explicit. read_document gives bounded, audit-logged, paged access to a document's stored Markdown by reference only. remember_document_use records that a document was used for something, as a byproduct of work already done in the turn -- never a reason for a separate model call. backfill_documents (also python -m fernme.backfill_documents) catalogs pre-Phase-18 document imports without duplicating events or graph edges. The agent may infer at most eight topical tags while already reading selected Markdown, but must link them to the document via propose_tags; FERNme never auto-accepts semantic tags. See docs/fernmark-document-adapter.md for the vault and lifecycle contract.

Photo memory (default off)

Install fernme[media], set [media] enabled = true in fern.toml, and use the two-step MCP flow remember_photo(..., confirm=false) followed by confirm=true only after the user agrees. JPEG, PNG, and WebP files are re-encoded without EXIF/GPS, stored in a local blob directory beside the SQLite database, and linked to agent-emitted tags as asset:<uuid> nodes; forget_photo deletes the files and graph evidence. Honest cost: this adds 0 extra model calls when tags ride an agent turn that already perceived the image. Silent or bulk ingestion without an agent is not implemented and is out of scope for this phase.

Minimal API example

from fernme.service import FernService

svc = FernService(db_path=":memory:")
svc.consent("shop.example", "elena", True)

svc.observe(
    "shop.example",
    "elena",
    "chat",
    {
        "tags": ["pref:concise", "pref:oat_milk"],
        "text": "Elena prefers concise answers and oat milk.",
    },
)

print(svc.card("shop.example", "elena")["wire"])

Typed entities are opt-in (entities=True, entity_aggregation=True):

from dataclasses import replace; from fernme.config import DEFAULT
svc = FernService(db_path=":memory:", cfg=replace(DEFAULT, entities=True, entity_aggregation=True)); svc.consent("demo.example", "alex", True)
alex = svc.entity_create("demo.example", "alex", "person", "Alex Chen")
dana = svc.entity_create("demo.example", "alex", "person", "Dana Reyes")
svc.entity_relate("demo.example", "alex", alex, "friend_of", dana)
print(svc.recall_path("demo.example", "alex", alex, dana))

🧱 What's inside

• Engine - zero-model-call Hebbian write/recall core, 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 catalog, free-text, and agent-supplied tags to one form (pref:, topic:, goal:, context:) so the same concept does not drift across months. The deterministic Obsidian importer uses the same vocabulary and queues wikilink aliases for review. Enrichment proposals are separate and human-approved.
• Structured-field capture — regex-only contact/date extraction keeps email, phone, URL, handle, and ISO-date values in the Cabinet payload as data, not tags.
• Typed entity layer - opt-in service APIs and additive SQLite/Postgres tables for entities, tag aliases, fields, Hebbian typed relations, relation facts, alias aggregation, and compact entity-aware card enrichment behind default-off flags.
• Propose-only enrichment - default-off propose_relation, propose_entity_link, and batch enrich(llm_fn=...) validation into the existing suggestion queue; human accept/reject is the only truth write trigger.
• The Cabinet — append-only event log with recall() for specific facts.
• Edge provenance — persisted stated/inferred authority metadata on graph edges across SQLite, Postgres, and consolidation undo.
• 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 bundled local React SPA at /ui/graph (graph, review queue, memory editor, feed, health; /graph redirects for old bookmarks).
• Governance — consent-gated everywhere; export & right-to-be-forgotten built in.

🔬 How FERNme compares

FERNme is a different category from conversational memories — it is a user-owned personalization graph evaluated by actions, not a transcript store optimized for QA recall. Don't benchmark it only 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 (283 passing, 2 skipped with FERNmark installed; 274 passing, 11 skipped without the optional extra): engine, SQLite + real-Postgres stores, supernode + sign-in, triggers, safety, REST/MCP, bundled local SPA, 2D/spatial memory graph view, canonical entity-kind filters, review-backed re-kind suggestions, selected-node evidence cards, class-targeted volatility retention, contradiction-scoped verify, persisted edge provenance, structured-field ingest, suggest-and-approve canonicalization, cross-user assoc k-suppression, deterministic Obsidian and FERNmark document import, MCP packaging smoke coverage, self-configuring install paths, and the full results suite above.

🆕 Typed entity layer: deterministic, consent-gated service APIs plus additive SQLite/Postgres tables for entities, aliases, fields, typed relations, and inert relation facts with Hebbian strengthening/decay. Opt-in retrieval integration can aggregate fragmented aliases and enrich card slots with compact entity context. It is validated on synthetic acceptance fixtures and the python -m fernme.eval.entities micro-eval; First real-profile validation (n=1, maintainer's own 722-tag profile): with entity flags on, a fragmented person's card rank improved 11→6, a previously-missed contact_of relationship surfaced in the card, and token cost stayed flat (~150 vs ~155). Synthetic-vs-real caveat applies: one profile, one probe set. Structured-field ingest now retains email, phone, URL, handle, and ISO-date extractions in event payloads as Cabinet data; entity-field writes are available through the service API, with automatic promotion left for a later pass.

Suggest-and-approve canonicalization: deterministic alias-merge and entity-link suggestions are persisted per site/user for human review. This is synthetic-validated by python -m fernme.eval.canonicalization (precision 1.000 +/- 0.000, recall 1.000 +/- 0.000 on planted duplicate aliases), opt-in at the service/API layer, and propose-only: rejected suggestions do not resurface, and accepted suggestions apply through existing entity alias APIs.

Propose-only enrichment: default-off agent/model proposal surfaces enqueue typed relation and entity-link candidates into the same review queue. With enrichment disabled, outputs are byte-identical and propose_*/enrich() are inert. With enrichment enabled, proposals are sanitized, vocabulary/entity-kind checked, counted when dropped, and never written to memory truth until accepted by a human. Synthetic mock eval: precision 1.000 +/- 0.000, recall 1.000 +/- 0.000, 2.000 suggestions/seed, and 1.000 FERNme-initiated batch LLM call/seed. Agent-driven proposals make 0 FERNme LLM calls. Cross-user assoc isolation: assoc graph reads are k-suppressed by default (assoc_min_users=2). This is a deliberate privacy-motivated behavior change on multi-user sites: one user's rare co-occurrence pair cannot influence another user's retrieval until at least two distinct users reinforce it. Single-user sites are unchanged because each user's own assoc contributions remain visible to them; assoc_min_users=1 is the compatibility escape hatch for the old shared-site behavior.

🆕 New default behavior: class-targeted volatility retention is on by default. Permanent facts use very long retention, volatile/current facts fade fast, and drift-tested taste classes stay short. Synthetic R5 retention eval: permanent facts above floor at day 700 improve 0.000 -> 1.000, stale volatile weight improves 2.114 -> 0.000, and slow changed facts still prefer the new value 1.000. Legacy focused drift checks remain regression coverage; cross-method claims use the unified harness above.

🆕 Verify scope: contradiction-scoped verify is on for genuine single-value-slot conflicts and marks only the older side of the contradiction. Synthetic R5 eval: contradicted-stale verify precision 1.000, recall 1.000, nag 0.000, with 0.959 +/- 0.156 conflict pairs/user. The perfect contradicted-stale score is by construction, so it validates wiring, not real-world conflict-detector quality. Confidence separates "keep it" from "trust it"; stale-high-confidence-wrong improves in the fixture (0.070 -> 0.004) because middle-class confidence no longer decays slower than flat.

🚧 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-to-attribute matching; optional propose-only enrichment for messy inputs.
• Silent staleness verify