Three claims, each reproducible

All numbers above come from synthetic, fictional message streams, not real users. FERNme does not win every recall benchmark; see the benchmarks for where simple baselines beat it. A real-model recall head-to-head against Mem0 is wired and owner-run.

Try it in 60 seconds

pip install "fernme[mcp] @ git+https://github.com/mirkofr/FERNme"

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"])   # the card your agent injects

Use it from Claude Code, Codex, or any MCP client: run fernme-mcp, or add the bundled plugin (/plugin marketplace add mirkofr/FERNme). See MCP and plugin packaging.

How it works

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

The full feature list (collective priors, supernode, style and mood memory, outcome learning, tamper-evident audit chain, and more) is in docs/features.md.

📊 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

Token race (FERNme vs full history vs Mem0's measured prompts): python -m fernme.eval.cost_race --turns 300 --with-mem0-prompts --json reports/cost_race.json --html token_race.html

Mem0 recall head-to-head (owner-run, needs an API key): python -m fernme.eval.mem0_h2h --check, then see docs/mem0-head-to-head.md

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 harness - synthetic hidden-answer-key scenarios for static, abrupt drift, gradual drift, staleness, contextual, fragmented-entity, outcome, and slot-change regimes (updated 2026-09-30: the fixtures no longer use FERNme's reserved style: namespace, which the card never shows and which had capped FERNme's recall; slot_change is new and tests one-value-at-a-time facts such as city or employer). 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. The slot-change regime was written together with the feature it tests (the newest confirmed value wins in single-value slots such as city or employer), so treat its FERNme rows as a mechanism check; plain recency still wins it.

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

git clone https://github.com/mirkofr/FERNme && cd FERNme
pip install -e ".[dev,api]"          # add ,fernmark / ,media / ,pgtest for the optional suites

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               # 338 passed, 61 skipped without the fernmark/media/pgtest extras

# 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 set the profile tools use, and lock MCP tools to it (see Agent safety below). For the graph UI dependencies, install pip install "fernme[ui]".

Two plugins live under packaging/ (Claude Code / Cowork and Codex layouts):

*Every tool description is loaded into each agent session, so the default plugin ships only the memory tools. Rough estimate (characters / 4).

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

For Claude Code CLI: /plugin marketplace add mirkofr/FERNme, then /plugin install fernme-memory@fernme-local (and optionally fernme-docs@fernme-local). For Cowork: Customize > Plugins > "+" > Add marketplace from GitHub > enter the repo URL > install fernme-memory.

The shipped configs run:

# fernme-memory
uvx --from "fernme[mcp] @ git+https://github.com/mirkofr/FERNme@v0.4.2" fernme-mcp --tools core
# fernme-docs (needs the FERNmark package)
uvx --with "<fernmark package>" --from "fernme[mcp] @ git+https://github.com/mirkofr/FERNme@v0.4.2" fernme-mcp --tools documents,photos

fernme-mcp --tools accepts core, documents, photos, all, or auto (default: core, plus documents/photos when FERNME_MANAGED_DOCUMENTS or [media] enabled turn them on). FERNME_MCP_TOOLS sets the same from the environment. Both plugins read and write one database (FERNME_DB), and concurrent writers are safe.

Cloud agents (OpenAI dots, xAI Grok Bot, and others that connect to remote MCP servers) use fernme-mcp --transport http with one token per agent, each locked to its own profile. Remote agents never get tools that read files on your machine, and only you approve consent and suggested merges; see docs/cloud-agents.md.

Agent safety on the MCP tools: grant_consent asks first (the agent must show the returned question and call again with confirm=true only after you say yes); setting FERNME_SITE / FERNME_USER locks the server to that profile so an agent cannot read or write another one (FERNME_ALLOW_OTHER_PROFILES=true turns the lock off); import_obsidian previews by default (dry_run=false to write). Every consent request also appears in the FERNme app's Review queue, where you can approve or deny it; FERNME_CONSENT_MODE=inbox makes that the only way to grant consent (the default for remote agents).

The plugins are pinned to the release tag v0.4.2, so external testers get the same server build once the owner pushes that tag. 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 @ git+https://github.com/mirkofr/FERNmark.git@23e16ea5b01f4ce77fee81b5bf4f7e0d87d77bae"
set FERNME_MANAGED_DOCUMENTS=true
set FERNME_VAULT=<vault-root>

The engine flag is default-off; the optional fernme-docs 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"])

Pinned settings are for choices a user states outright ("always use box plots"). One value per key, they never fade, and every card lists all of them, whatever the context, card budget or population prior:

svc.set_setting("shop.example", "elena", "plot.style", "box", text="I like box plots")
svc.card("shop.example", "elena")["settings"]      # {'plot.style': 'box'}
svc.clear_setting("shop.example", "elena", "plot.style")

Embedding FERNme in a server app (Postgres schema, connection pool, migrations as a deploy step, per-user locking, hosted multi-user rules) is covered in docs/embedding.md and the hosted section of SECURITY.md.

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 (338 passed, 61 skipped on Python 3.11 without the optional fernmark, media, and pgtest extras; checked on 2026-09-30 with mcp 1.30 and 2.2): 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) recall head-to-head — fernme.eval.mem0_h2h runs real Mem0 on the harness scenarios; needs OPENAI_API_KEY (how).
• Embeddings for context-to-attribute matching; optional propose-only enrichment for messy inputs.
• Silent staleness verify -- age-only verify remains off by default. In the synthetic sweep, the best age-only point was still weak (precision 0.461, recall 0.651, nag 0.214), so silent-stale detection needs the next milestone: learned per-edge volatility or outside corroboration.

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 (zero-model-call core) · Hebbian update · decay
  retrieve/  base-level + spreading activation · token-minimal card · entity_card.py
  capture/   adapters · extractors.py (regex-only structured fields)
  prior/     population prior · differential encoding · IDF cold-start
  store/     sqlite_store · postgres_store (one interface)
  relations.py · typed entity/relation vocabulary
  supernode.py · auth.py · triggers.py · safety.py · service.py
  api/       rest.py (FastAPI) · mcp_server.py · serve.py
  web/       app/ (React SPA source) · static/app/ (bundled local UI assets)
  eval/      simulator - cost - quality - drift - context - ablation - pilot - entities - harness - enrichment
tests/       338 passed, 61 skipped without optional extras   ·   *_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.