Before the code: the one idea everything follows from

Every module in this repo obeys the same handful of rules. Once these are load-bearing in your head, the actual code stops looking like 16 separate modules and starts looking like one idea applied 16 times.

Degrade, never fail

No LLM reachable? Facts get stored verbatim instead of extracted. No embeddings? Search falls back to keyword-only. No Redis? No hot turns, no cache — capture still lands. Every external dependency raises a typed exception on failure (LlmUnavailable, EmbeddingsUnavailable) and every caller has a fallback for it. You'll see this pattern constantly: a try/except SpecificError where the except branch isn't an error handler, it's a second, dumber, fully-functional code path.

Supersede, never delete

An "update" doesn't overwrite a row — it writes a brand-new fact and flags the old one is_active=false. A contradiction doesn't get auto-resolved — it gets logged and both facts stay. This is a deliberate stance: memory systems that silently pick a winner between two things you said are making a judgment call you didn't ask for.

The vault is truth; the databases are indexes

DuckDB and Qdrant exist purely to make search fast. If you deleted them both and kept only the vault/ folder, you'd have lost nothing except search speed — every fact is still sitting there as a readable markdown file. This is why reads always go back to disk (vault.read_note re-reads the file every time) instead of trusting a cached copy: a hand edit in Obsidian has to be the truth, immediately, with no sync step.

The format: app/core/okf.py

Start here because it has zero dependencies on anything else in the repo — no database, no filesystem, no config. It's pure text transformation, which makes it the easiest place to build a mental model before anything gets stateful.

An OKF note is just this:

---
id: scene_8f9a2b
type: scene
created: 2025-07-08T14:30:00Z
---
# Scene: ...
body with [[wikilinks]]

Two functions do all the work. render_note turns a dict + string into that text. parse_note turns it back. The interesting part is what happens when parsing fails:

def parse_note(raw: str) -> tuple[dict, str]:
    """Splits a note into (frontmatter dict, body). A file without valid
    frontmatter — e.g. a note the user created by hand in Obsidian — parses
    as ({}, whole file) rather than erroring; hand-edited files are a
    first-class input in this system, never a corruption case."""
    match = _FRONTMATTER_PATTERN.match(raw)
    if not match:
        return {}, raw.strip()
    try:
        frontmatter = yaml.safe_load(match.group(1)) or {}
        if not isinstance(frontmatter, dict):
            return {}, raw.strip()
    except yaml.YAMLError:
        return {}, raw.strip()
    return frontmatter, raw[match.end() :].strip()

The wikilink bug that a real screenshot caught

This is worth reading closely because it's a genuine bug-and-fix you can trace end to end, not a toy example:

def wikify(text: str, entities: list[str]) -> str:
    for entity in sorted(entities, key=len, reverse=True):
        pattern = re.compile(
            r"(?<!\[\[)" + re.escape(entity) + r"(?!\]\])(?![^\[]*\]\])"
        )
        slug = slugify(entity)
        replacement = f"[[{entity}]]" if slug == entity.lower() else f"[[{slug}|{entity}]]"
        text = pattern.sub(replacement, text, count=1)
    return text

The highlighted line is the whole lesson. slugify("Iron Temple") produces "iron-temple" — but a plain [[Iron Temple]] wikilink never resolves to a file named iron-temple.md in Obsidian, because Obsidian's link matcher is case-insensitive but doesn't turn spaces into hyphens. The fix uses Obsidian's own alias syntax — [[slug|Display Text]] — so the link points at the real file while still showing the human-readable name. Single-word entities like Sarah skip the alias entirely, because slugify("Sarah") already equals "sarah" and case-insensitivity alone covers that.

The brain on disk: app/core/vault.py

This is where okf.py's pure functions meet an actual filesystem. Every function here does exactly one filesystem operation and has one job. Two are worth understanding closely because they encode the "vault is truth" rule as actual behavior, not just a comment.

def ensure_entity_stub(tenant_id: str, user_id: str, entity_name: str) -> Path:
    """Creates entities/{slug}.md if missing. Never overwrites an existing
    note — the user may have enriched it by hand, and their version wins."""
    entities_dir = _user_root(tenant_id, user_id) / "entities"
    entities_dir.mkdir(parents=True, exist_ok=True)
    path = entities_dir / f"{okf.slugify(entity_name)}.md"
    if not path.exists():
        frontmatter = {"type": "entity", "created": ..., "aliases": []}
        path.write_text(okf.render_note(frontmatter, f"# {entity_name}\n"), encoding="utf-8")
    return path

That single if not path.exists() is the entire "your edits win" guarantee. Every time Mimir mentions an entity again, it calls this function again — and every time after the first, it's a no-op. If you'd opened that note and written three paragraphs about your coach, this function will never touch it again.

The graph walk

This is the function that makes recall feel associative instead of purely keyword-driven — it's a plain breadth-first search over wikilinks, capped at a hop count:

def expand_links(tenant_id, user_id, bodies: list[str], hops: int = 2) -> dict[str, str]:
    index = _note_index(tenant_id, user_id)
    collected: dict[str, str] = {}
    frontier = [t for body in bodies for t in okf.extract_wikilinks(body)]

    for _ in range(hops):
        next_frontier: list[str] = []
        for target in frontier:
            slug = okf.slugify(target)
            if target in collected or slug not in index:
                continue
            _, note_body = okf.parse_note(index[slug].read_text(encoding="utf-8"))
            collected[target] = note_body
            next_frontier.extend(okf.extract_wikilinks(note_body))
        frontier = next_frontier
    return collected

The write path, in execution order

Everything from here on is stateful, so reading order matters more than file order. Follow one conversation through the system exactly as app/core/pipeline.py calls it — this is the actual sequence, not a simplification:

capture() — the only part that has to succeed

def capture(tenant_id, user_id, session_id, messages: list[dict]) -> list[str]:
    for offset, message in enumerate(messages):
        message_id = str(uuid.uuid4())
        duckdb_client.insert_l0_message(...)   # must succeed
        message_ids.append(message_id)
        try:
            redis_client.push_turn(...)         # best-effort
        except Exception:
            logger.warning("hot memory push failed (redis unreachable?) — capture continues")
    return message_ids

Notice the asymmetry: the DuckDB write has no try/except at all — if that fails, the whole request should fail, because losing what you said is not an acceptable outcome. The Redis write is wrapped, because losing a speed optimization is fine.

synthesize_scene() — the LLM-or-digest fork

app/core/synthesis.py turns raw turns into the human- readable scene note. It tries an LLM call for real prose; on any failure it falls back to a deterministic transcript digest — same output shape either way (a title, a body, a list of entities), so nothing downstream needs to know which path ran.

extract_facts() — turns into atomic facts

app/core/extraction.py is the same fork, applied to L1 facts instead of the scene note: LLM path returns typed, prioritized facts; offline path stores each substantive user turn verbatim, tagged extraction: verbatim so you can tell later which facts were ever actually processed by a model.

consolidate() — the dedup gate

app/core/consolidation.py is the most subtle file in the repo, so it's worth reading in full rather than skimming. Two layers, cheapest first:

# layer 1 — free, always runs, catches exact duplicates before any LLM call
candidate_norms = {_normalize(c["content"]): cid for cid, c in candidates.items()}
for fact in new_facts:
    norm = _normalize(fact["content"])
    if norm in candidate_norms or norm in seen_new_norms:
        continue   # dropped — never even reaches the LLM
    surviving.append(fact)

Only what survives layer 1 goes to the LLM, batched into one call that sees every new fact plus a pool of keyword-nearest existing memories, and returns a store/skip/update decision per fact. This next line is the one worth studying hardest in the whole file:

valid_ids = set(candidates)
...
fact["_supersedes"] = target if verdict == "update" and target in valid_ids else None

maybe_synthesize() — the persona, refreshed on a counter

app/core/persona.py re-writes the persona doc every l3_every_n_memories new facts. The trigger count isn't stored in a database — it's stored in the persona note's own frontmatter (fact_count), so the vault stays the single source of truth even for "when did this last run."

The four stores

You already know what each of these technologies does in general. Here's specifically how Mimir uses them, and the one thing about each that isn't obvious from the name.

The read path: scoring + recall

This is the payoff — the part that actually answers a query. Read scoring.py first since it's pure math with no side effects, then recall.py, which is just scoring.py wired up to the stores from stage 4.

Four signals, one formula

def final_score(semantic, frequency, recency, graph):
    w = settings.recall.weights
    return semantic * w.semantic + frequency * w.frequency + recency * w.recency + graph * w.graph

Each input is computed by its own tiny function, and each is worth reading once:

def recency_score(created_at, now=None):
    """e^(-decay_rate * age_days); today ~1.0, ~14 days ago ~0.5 at the 0.05 default."""
    age_days = max((now - created_at).total_seconds() / 86400, 0.0)
    return math.exp(-settings.recall.decay_rate * age_days)

def frequency_score(access_count, max_access_count):
    """log-normalized so one obsessively-recalled memory doesn't flatten
    the signal for everything else."""
    if max_access_count <= 0 or access_count <= 0:
        return 0.0
    return math.log(1 + access_count) / math.log(1 + max_access_count)

graph_score is the simplest of the four — it's just a lookup table, {0: 1.0, 1: 0.5, 2: 0.25}, mapping wikilink hop-distance to a score. No formula needed because the input is already a small integer.

The one line that makes hybrid search actually hybrid

In recall.py, after BM25 and vector search each return their own ranked list:

keyword_ranking = [f["id"] for f in keyword_hits]
vector_ranking = sorted(semantic_by_id, key=semantic_by_id.get, reverse=True)
rrf = scoring.rrf_merge([keyword_ranking, vector_ranking])

and in scoring.py:

def rrf_merge(ranked_lists: list[list[str]]) -> dict[str, float]:
    """Reciprocal Rank Fusion: id -> summed 1/(k + rank) across every list
    it appears in. Scale-free, so BM25 scores and cosine similarities never
    need to be made comparable — only their rankings matter."""
    scores = {}
    for ranked in ranked_lists:
        for rank, item_id in enumerate(ranked):
            scores[item_id] = scores.get(item_id, 0.0) + 1.0 / (RRF_K + rank + 1)
    return scores

Reading the fallback in context

One line worth slowing down on, since it looks small but encodes a real design decision:

semantic = semantic_by_id.get(fact_id, rrf.get(fact_id, 0.0) / max_rrf if not vector_used else 0.0)

When the vector leg actually ran, a fact's semantic score is its real cosine similarity. When there's no embedding endpoint configured at all, there's no cosine score to fall back on — so the normalized RRF rank stands in for it instead, which means keyword relevance still drives the final ranking even with zero AI models involved anywhere in the request.

The front doors

Everything above this line is the engine. Everything here is how something outside Python actually talks to it.

The semantic cache — the cheapest possible answer

semantic_cache.py checks two things before recall ever runs a real search: an exact hash of the normalized query (works with zero embeddings), then a cosine similarity against previously-cached query vectors at a 0.92 threshold. A hit on either returns instantly. Invalidation is deliberately blunt — any new memory landing for a user wipes their entire cache, not just entries that might be stale, because a wrong cached answer is worse than a slightly wasted recomputation.

Two MCP adapters, one shared engine

This is the part worth understanding if you're going to actually use this day to day. adapters/mcp_embedded.py imports app.core.pipeline directly — no network call, no server process, the engine runs inside the same Python process the MCP client spawned. adapters/mcp_server.py does the exact same three tools but via HTTP to a running gateway. Same tools, same ~/.mimir files either way — the only difference is whether there's a process in between.

Exercises — break it on purpose

Reading code teaches you what it does. Changing it and watching what breaks teaches you why it's built that way. Try these roughly in order: