engram-lite 0.1.0__py3-none-any.whl

engram/__init__.py

@@ -0,0 +1,30 @@
+"""engram — a small, local-first agentic memory engine.
+
+One SQLite file holds the facts, a keyword index (FTS5), and a vector index
+(sqlite-vec). Meant to be shared across your AI tools (Claude, Cursor, …) and
+across sessions. See docs/memory-docs/ for the design and docs/code-docs/ for the
+code guide.
+
+Quick start:
+
+    from engram import Memory
+    mem = Memory("my_memory.db")
+    mem.save("Bob owns the payments service", subject="Bob")
+    mem.search("who owns payments?", subject="Bob")
+
+Layout:
+    engram.core         the engine logic (memory, consolidation, retrieval, …)
+    engram.storage      SQLite connection, schema, row/index operations
+    engram.embeddings   text → vector (local model, with a stub fallback)
+    engram.cli          the `engram` command (demo / status / rebuild)
+"""
+
+from .core.memory import Memory
+from .embeddings import get_embedder
+
+__all__ = ["Memory", "get_embedder"]
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("engram-lite")
+except Exception:  # not installed (running from a checkout)
+    __version__ = "0.1.0"

engram/cli/__init__.py

@@ -0,0 +1,5 @@
+"""The `engram` command-line interface."""
+
+from .main import main
+
+__all__ = ["main"]

engram/cli/demo.py

@@ -0,0 +1,60 @@
+"""`engram demo` — an interactive REPL to see the engine work (no AI tool needed).
+
+For each line you type: FIND relevant memories, then SAVE the salient ones.
+"""
+from __future__ import annotations
+
+import argparse
+
+from ..core.memory import Memory
+
+
+def run(args: argparse.Namespace) -> int:
+    mem = Memory(path="engram_demo.db")
+    print("engram demo — type a message, or :quit. (:help for commands)\n")
+    pinned_subject = None
+    while True:
+        try:
+            line = input("you> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not line:
+            continue
+        if line in (":quit", ":q"):
+            break
+        if line in (":help", ":h"):
+            print("  :list  :forget <id>  :subject <name>  :quit")
+            continue
+        if line == ":list":
+            for f in mem.all_current():
+                print(f"  [{f['id'][:8]}] ({f['block_id']}) {f['value']}")
+            continue
+        if line.startswith(":forget "):
+            mem.forget(line.split(" ", 1)[1].strip())
+            print("  forgotten.")
+            continue
+        if line.startswith(":subject "):
+            pinned_subject = line.split(" ", 1)[1].strip()
+            print(f"  subject pinned: {pinned_subject}")
+            continue
+
+        hits = mem.search(line, k=3)
+        if hits:
+            print("  🧠 recalled:")
+            for h in hits:
+                print(f"     - {h['value']}")
+        else:
+            print("  🧠 (nothing relevant remembered yet)")
+        res = mem.remember(line, subject=pinned_subject)   # gated save (salience)
+        if res["decision"] == "SKIP":
+            print(f"  · skipped — {res['reason']}")
+        else:
+            print(f"  💾 {res['decision']} → block '{res['block_id']}'")
+        print()
+    mem.close()
+    return 0
+
+
+def add_parser(sub) -> None:
+    sub.add_parser("demo", help="interactive demo REPL").set_defaults(func=run)

engram/cli/main.py

@@ -0,0 +1,99 @@
+"""The `engram` command — dispatches to subcommands.
+
+  engram demo      interactive REPL
+  engram status    print current env settings
+  engram rebuild   re-embed a store after changing the embedding model
+"""
+from __future__ import annotations
+
+import argparse
+
+from . import demo
+
+
+def _run_selftest(args: argparse.Namespace) -> int:
+    """Verify the engine works end-to-end (offline, no model download)."""
+    import os
+    import tempfile
+
+    from ..core.memory import Memory
+    from ..embeddings import HashEmbedder
+
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    try:
+        m = Memory(path, embedder=HashEmbedder())
+        m.remember("selftest: the payments service is owned by Bob", subject="selftest")
+        hits = m.search("who owns payments?", subject="selftest")
+        m.close()
+        if hits:
+            print("✓ engine OK — sqlite-vec + FTS5 + vector search working")
+            return 0
+        print("✗ engine ran but recall failed")
+        return 1
+    except Exception as exc:  # noqa: BLE001
+        print(f"✗ engine FAILED: {exc}")
+        return 1
+    finally:
+        os.unlink(path)
+
+
+def _run_rebuild(args) -> int:
+    from ..core.memory import Memory
+    res = Memory.reembed(args.db)
+    print(f"re-embedded {res['reembedded']} facts at {res['dim']}-dim "
+          f"({res['model']}) — store ready")
+    return 0
+
+
+def _run_status(args: argparse.Namespace) -> int:
+    import os
+    import sqlite3
+
+    from .. import config
+    from ..settings import Settings
+
+    s = Settings.from_env()
+    print(s.summary())
+    # show "how full" without loading the embedding model — a plain sqlite read
+    if os.path.exists(s.db_path):
+        con = sqlite3.connect(s.db_path)
+        try:
+            cur = con.execute(
+                "SELECT COUNT(*) FROM facts WHERE superseded_by IS NULL "
+                "AND validation_status = 'fresh'"
+            ).fetchone()[0]
+            tot = con.execute("SELECT COUNT(*) FROM facts").fetchone()[0]
+            pages = con.execute("PRAGMA page_count").fetchone()[0]
+            psize = con.execute("PRAGMA page_size").fetchone()[0]
+            print(f"usage: {cur} current / {tot} total facts · cap {config.MAX_FACTS} "
+                  f"· db {pages * psize / 1024:.0f} KB")
+        except sqlite3.Error:
+            print("usage: (no memory yet)")
+        finally:
+            con.close()
+    else:
+        print("usage: (no DB at this path yet)")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="engram", description="engram — local agentic memory")
+    sub = parser.add_subparsers(dest="command")
+
+    demo.add_parser(sub)
+    sub.add_parser("status", help="print the current env settings").set_defaults(func=_run_status)
+    sub.add_parser("selftest", help="verify the engine works (offline)").set_defaults(func=_run_selftest)
+    rb = sub.add_parser("rebuild", help="re-embed a store after changing ENGRAM_EMBEDDER_MODEL")
+    rb.add_argument("db", help="path to the memory .db file")
+    rb.set_defaults(func=_run_rebuild)
+
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engram/config.py

@@ -0,0 +1,79 @@
+"""Build-time knobs — constants the engine is tuned with.
+
+Distinct from `settings.py`, which reads *runtime* flags from environment variables.
+"""
+from __future__ import annotations
+
+# ── storage ──────────────────────────────────────────────────────────────────
+DEFAULT_DB_PATH = "engram.db"   # one SQLite file holds everything (STORAGE_AND_RETRIEVAL §3)
+
+# ── embeddings ───────────────────────────────────────────────────────────────
+EMBED_MODEL = "BAAI/bge-small-en-v1.5"  # small, local, offline model (fastembed)
+FALLBACK_DIM = 384                       # dim of the hash-stub embedder + bge-small
+# Pin the model cache to a STABLE dir so it downloads once and stays offline —
+# fastembed's default is $TMPDIR, which the OS wipes (silent re-downloads).
+# Override with ENGRAM_MODEL_CACHE.
+MODEL_CACHE_DIR = "~/.cache/engram/models"
+
+# ── consolidation thresholds (cosine similarity, 0..1) ───────────────────────
+# Four-way operation set: ADD / UPDATE / DELETE / NOOP — here NOOP is upgraded
+# to REINFORCE (bump confidence instead of silently dropping the duplicate).
+REINFORCE_SIM = 0.97   # ~identical to an existing fact → just bump it, no new row
+UPDATE_SIM = 0.86      # close enough to be the same fact → refine, contradict, or supersede
+
+# ── extraction (one interaction → several atomic facts) ──────────────────────
+# The write path's biggest quality lever: split a message into discrete, reusable facts
+# instead of storing it as one blob (MEMORY_LIFECYCLE §2).
+MAX_FACTS_PER_INTERACTION = 8  # cap on candidates pulled from a single remember() call
+
+# ── retrieval ────────────────────────────────────────────────────────────────
+CANDIDATES_PER_CHANNEL = 30   # how many to pull from keyword, vector, and entity search
+RRF_K = 60                     # Reciprocal Rank Fusion constant (INDEXING_DEEP_DIVE §7)
+DEFAULT_TOP_K = 5              # how many memories to return by default
+SEARCH_K_CAP = 200            # k is clamped to [1, this]: a mistyped/hostile k must
+                              # neither blow the knn query limit nor blackout serving
+LEDGER_CAP = 2000             # decision-ledger rows kept (capped rotation)
+ENTITY_RERANK_BONUS = 0.15    # multiplicative boost per query entity a fact names
+                              # (max 3); tuned on LoCoMo dev convs 26+30 ONLY
+
+# framework-stamped pseudo-tags that carry no task information — treating them
+# as a lane caused a total silent serving blackout (loss census P1)
+GENERIC_TASK_TAGS = frozenset({
+    "conversation", "chat", "general", "message", "misc", "context", "default",
+    "session", "dialogue", "turn",
+})
+MIN_SIMILARITY = 0.30         # vector candidates below this cosine are dropped (noise floor)
+
+# recency: at equal relevance, fresher memories rank higher (INDEXING_DEEP_DIVE §7).
+# final_score = rrf_score × ((1 - RECENCY_WEIGHT) + RECENCY_WEIGHT × freshness),
+# where freshness = 0.5 ** (age_days / RECENCY_HALFLIFE_DAYS) ∈ (0, 1].
+RECENCY_WEIGHT = 0.30          # how much recency may tilt the ranking (0 = off)
+RECENCY_HALFLIFE_DAYS = 30.0   # a memory this old contributes half its freshness
+
+# ── entities (the third retrieval signal) ────────────────────────────────────
+ENTITY_MIN_LEN = 2            # ignore entity tokens shorter than this
+
+# common words ignored in the keyword (FTS) query so it doesn't match everything
+STOPWORDS = {
+    "a", "an", "the", "is", "are", "was", "were", "be", "to", "of", "in", "on",
+    "for", "and", "or", "i", "you", "we", "it", "this", "that", "what", "who",
+    "whom", "how", "why", "when", "where", "should", "would", "could", "my",
+    "your", "our", "here", "there", "do", "does", "did", "use", "used", "can",
+    "will", "with", "about", "from", "at", "as", "by", "me", "s",
+}
+
+# ── conditioned promotion (the lane model — see core/promotion.py) ───────────
+PROMOTION_FLOOR_FRAC = 0.34   # keep a fact only if score >= this fraction of the top score
+PROMOTION_EPSILON = 0.05      # weight of the word-overlap tie-break signal
+PROMOTION_OVERFETCH = 4       # promotion re-ranks OVERFETCH×k retrieval candidates
+PROMOTION_MIN_CANDIDATES = 30 # ...but never fewer than this many candidates
+LANE_FETCH_LIMIT = 100        # lane channel: max lane-tagged facts added as candidates
+TAGS_PER_FACT_CAP = 8         # max tags stored per fact
+
+# ── salience (what to save) + compaction (how compactly) ─────────────────────
+KEY_CHAR_CAP = 160            # the short embedded label is trimmed to this
+VALUE_CHAR_CAP = 1000         # the stored value is capped (guardrail against blobs)
+MAX_TEXT_CHARS = 2000         # longer than this → assumed file/output dump, skip saving
+
+# ── size limit / eviction ────────────────────────────────────────────────────
+MAX_FACTS = 5000              # per DB; least-used facts are evicted beyond this

engram/core/__init__.py

@@ -0,0 +1,5 @@
+"""The engine logic: orchestration, extraction, consolidation, entities, retrieval, fusion."""
+
+from .memory import Memory
+
+__all__ = ["Memory"]

engram/core/anchors.py

@@ -0,0 +1,101 @@
+"""Anchor tokens — the parts of a fact that make it THAT fact.
+
+"orders p99 is 450ms" and "refunds p99 is 450ms" share almost every word, but
+each carries a content token the other lacks. Any merge / collapse / invalidate
+decision between two such texts is a guess, and losing a true fact is worse
+than keeping a near-sibling.
+
+The guard is only consulted AFTER a caller has established near-identity
+(consolidation: cosine ≥ 0.86 on the same block; serve-time collapse:
+Jaccard ≥ 0.6) — inside a frame that similar, a differing content stem is not
+paraphrase variance, it is the identity of a different fact. One-sided
+differences (only one text has a negator, or extra detail) do NOT trigger:
+that's the genuine update/negation case the write path exists to handle.
+
+Loss census (2026-07-05) receipts: the UPDATE band silently superseded sibling
+facts at cos 0.86-0.95, DELETE false-fired on motion verbs, and serve-time
+near-dup collapse hid 8/12 distinct sibling pairs.
+"""
+from __future__ import annotations
+
+import re
+from typing import Set
+
+# words that flip a statement's polarity — genuine negators only. Motion /
+# completion verbs ("dropped the kids at school", "the meeting ended") are NOT
+# negation; they false-fired the DELETE path (census) and live nowhere here.
+NEGATORS = {
+    "not", "no", "never", "isn't", "aren't", "wasn't", "weren't", "don't",
+    "doesn't", "didn't", "won't", "can't", "cannot", "longer",     # "no longer"
+    "cancelled", "canceled", "discontinued", "deprecated",
+}
+
+_STOP = {
+    "the", "a", "an", "of", "to", "and", "or", "for", "with", "on", "in", "at",
+    "is", "are", "was", "were", "has", "have", "had", "be", "been", "its",
+    "it's", "this", "that", "these", "those", "every", "each", "all", "some",
+    "we", "our", "they", "their", "he", "she", "his", "her", "you", "your",
+    "i", "my", "me", "now", "then", "also", "very", "just", "will", "would",
+}
+
+_TOKEN = re.compile(r"[A-Za-z0-9'’\-]+")
+
+
+def _stem(tok: str) -> str:
+    """Cheap derivational stem so 'deploys'/'deploying'/'deployed' agree.
+    Only used for anchor comparison — never stored."""
+    for suf in ("ing", "ed", "es", "s"):
+        if tok.endswith(suf) and len(tok) - len(suf) >= 3:
+            tok = tok[: -len(suf)]
+            if len(tok) >= 2 and tok[-1] == tok[-2]:
+                tok = tok[:-1]
+            break
+    return tok[:-1] if tok.endswith("e") else tok
+
+
+def _strong_weak(text: str) -> tuple[Set[str], Set[str]]:
+    """STRONG anchors are definitive identity tokens: digits ("450ms",
+    "Tuesday at 10am"'s 10am), negators, and mid-sentence capitalized words
+    (names, days, products). WEAK anchors are the remaining content stems."""
+    strong: Set[str] = set()
+    weak: Set[str] = set()
+    for i, tok in enumerate(_TOKEN.findall(text or "")):
+        low = tok.lower()
+        if any(c.isdigit() for c in tok):
+            strong.add(low)
+        elif low in NEGATORS:
+            strong.add(low)
+        elif i > 0 and tok[0].isupper():
+            strong.add(_stem(low))
+        elif len(low) >= 3 and low not in _STOP:
+            # drop apostrophes BEFORE stemming: "lot's" → lots → lot (a
+            # trailing-strip left "lot'" and the filler floor never matched)
+            weak.add(_stem(low.replace("'", "").replace("’", "")))
+    return strong, weak
+
+
+def anchor_tokens(text: str) -> Set[str]:
+    """All identity-bearing tokens of a fact (strong ∪ weak)."""
+    strong, weak = _strong_weak(text)
+    return strong | weak
+
+
+def exclusive_anchors(a: str, b: str) -> bool:
+    """True when the two near-identical texts are DIFFERENT facts.
+
+    Two signals, both deterministic:
+      1. strong anchors differ on both sides — "payments deploys Tuesday" vs
+         "... Thursday", "p99 450ms" vs a different number owner, one side
+         negated per anchor asymmetry;
+      2. a 1-for-1 content-stem substitution in an otherwise shared frame —
+         "Bob owns payments" vs "Bob owns refunds". Paraphrases differ by
+         ADDITIVE wording (several extra stems on one or both sides), never by
+         a clean substitution, so genuine rewordings still merge/collapse.
+    """
+    sa, wa = _strong_weak(a)
+    sb, wb = _strong_weak(b)
+    if (sa - sb) and (sb - sa):
+        return True
+    ea = wa - wb - sb
+    eb = wb - wa - sa
+    return len(ea) == 1 and len(eb) == 1

engram/core/compaction.py

@@ -0,0 +1,51 @@
+"""Keep each memory small, so it costs little to store and few tokens to return.
+
+  - `compact_key`  → a short one-line label (the thing we embed + the handle).
+  - `cap_value`    → the full text, trimmed to a guardrail length.
+
+This is the cheap, offline version of "summarize the memory." A real LLM summary
+could fill the same role (MEMORY_LIFECYCLE §2/§6); here we just normalize + trim.
+"""
+from __future__ import annotations
+
+import re
+
+from .. import config
+from . import anchors
+
+# first-sentence boundary with the SAME digit + abbreviation guards extraction
+# uses: without them "Priorities: 1." and "Dr." became the embedded key and the
+# consolidation handle — matching nothing at recall and colliding across every
+# "Dr. X" fact (loss census P1)
+_FIRST_SENTENCE = re.compile(
+    r"(?<=[^\d][.!?])"
+    r"(?<!\b[A-Z]\.)(?<!Dr\.)(?<!Mr\.)(?<!Mrs\.)(?<!Ms\.)(?<!St\.)(?<!Ave\.)"
+    r"(?<!Blvd\.)(?<!Prof\.)(?<!Jr\.)(?<!Sr\.)(?<!vs\.)(?<!e\.g\.)(?<!i\.e\.)(?<!etc\.)"
+    r"\s"
+)
+
+
+def compact_key(text: str, cap: int = config.KEY_CHAR_CAP) -> str:
+    """A short, clean one-liner: collapse whitespace, take the first sentence, trim.
+
+    When the cap truncates, anchor tokens (names/numbers) from the cut tail are
+    appended — they're what makes the fact findable, and losing them made
+    semantic match on the cut content impossible (loss census P1).
+    """
+    t = " ".join(text.split())
+    first = _FIRST_SENTENCE.split(t, maxsplit=1)[0]
+    if len(first) <= cap:
+        return first
+    head = t[:cap].rsplit(" ", 1)[0]
+    lost = anchors.anchor_tokens(t) - anchors.anchor_tokens(head)
+    if lost:
+        head = f"{head} {' '.join(sorted(lost)[:4])}"[: cap + 48]
+    return head
+
+
+def cap_value(text: str, cap: int = config.VALUE_CHAR_CAP) -> str:
+    """The full memory text, capped so a stray long paste can't bloat the store."""
+    t = text.strip()
+    if len(t) <= cap:
+        return t
+    return t[:cap].rsplit(" ", 1)[0] + " …"

engram/core/consolidation.py

@@ -0,0 +1,91 @@
+"""The "is this new or already known?" decision (MEMORY_LIFECYCLE §5).
+
+Given a new fact's vector + key and its block, look at the nearest existing fact
+*in that block* and classify the write into a four-way operation set:
+
+    REINFORCE  near-identical (≥ REINFORCE_SIM)              → bump confidence, no new row
+    DELETE     same topic but the new fact NEGATES the old   → retire the stale belief, add new
+    UPDATE     same topic, refined/changed value             → supersede the old version
+    ADD        nothing close enough                          → brand-new fact
+
+(The "already known, do nothing" case is often called NOOP; here it becomes REINFORCE
+so repetition strengthens a memory instead of being silently dropped.)
+
+Pure decision logic — it does not write; `memory.py` applies the result via the
+repository. Contradiction is detected deterministically (negation polarity); a
+semantic LLM resolver could be slotted in behind this same contract.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional, Tuple
+
+from .. import config
+from ..storage import repository
+from . import anchors
+
+# words/markers that flip a statement's polarity ("Bob no longer owns payments").
+# Motion/completion verbs (dropped/stopped/ended/removed) are NOT here: "Bob
+# dropped the kids at school" is an event, not a negation — with them in the
+# list it invalidated Bob's standing routine (loss census 2026-07-05).
+_NEGATIONS = (
+    "not", "no longer", "never", "isn't", "aren't", "wasn't", "weren't", "don't",
+    "doesn't", "didn't", "won't", "can't", "cannot",
+    "deprecated", "cancelled", "canceled", "discontinued", "no more",
+)
+_NEG_RE = re.compile(r"\b(" + "|".join(re.escape(n) for n in _NEGATIONS) + r")\b", re.IGNORECASE)
+
+
+def _cosine_from_l2(distance: float) -> float:
+    """For unit vectors, euclidean^2 = 2 - 2cos  ⇒  cos = 1 - d^2/2."""
+    return 1.0 - (distance * distance) / 2.0
+
+
+def _has_negation(text: str) -> bool:
+    return bool(_NEG_RE.search(text or ""))
+
+
+def _contradicts(old_key: str, new_key: str) -> bool:
+    """True when one statement negates the other (opposite polarity)."""
+    return _has_negation(old_key) != _has_negation(new_key)
+
+
+def _nearest_in_block(conn, block_id: str, vec) -> Optional[Tuple[str, float, str]]:
+    for fid, dist in repository.nearest(conn, vec, k=10):
+        row = repository.get(conn, fid)
+        if row is None or row["superseded_by"] is not None:
+            continue
+        if row["validation_status"] != "fresh":
+            continue
+        if row["block_id"] != block_id:
+            continue
+        return fid, _cosine_from_l2(dist), row["key"]
+    return None
+
+
+def decide(conn, block_id: str, vec, key: str = "") -> Tuple[str, Optional[str], str]:
+    """Return (operation, target_fact_id, note). target is None for ADD.
+
+    `note` is non-empty when a merge was DEMOTED by the anchor guard — the
+    caller records it in the decision ledger so demotions are auditable.
+    """
+    nearest = _nearest_in_block(conn, block_id, vec)
+    if nearest is None:
+        return "ADD", None, ""
+    fid, sim, old_key = nearest
+
+    if sim >= config.UPDATE_SIM:
+        # anchor guard: if each statement carries an identity token the other
+        # lacks (orders vs refunds, Tuesday vs Thursday), these are two TRUE
+        # sibling facts however similar the wording — merging/retiring either
+        # one destroys real memory. Keep both. (Loss census 2026-07-05.)
+        if anchors.exclusive_anchors(old_key, key):
+            return "ADD", None, f"merge demoted: exclusive anchors vs {fid} (cos {sim:.2f})"
+        # same topic: does the new statement contradict (negate) the old one?
+        if _contradicts(old_key, key):
+            return "DELETE", fid, ""
+        if sim >= config.REINFORCE_SIM:
+            return "REINFORCE", fid, ""
+        return "UPDATE", fid, ""
+
+    return "ADD", None, ""

engram/core/dates.py

@@ -0,0 +1,129 @@
+"""Deterministic relative-date resolution at capture time.
+
+People state facts in relative time — "I went last Friday", "we're moving next
+month" — and the absolute date exists only in the conversation's own timestamp.
+LLM-extraction systems resolve this during ingestion with a model call;
+we resolve it with calendar arithmetic: zero LLM, same information.
+
+`resolve_relatives(text, anchor)` annotates each relative expression inline
+with its computed absolute form: "I went last Friday [= Friday, 14 July 2023]".
+Inline (not appended) so keyword/vector retrieval keeps the date next to the
+event it dates. Text inside existing [= ...] annotations is never re-annotated.
+
+Measured motivation (LoCoMo track B): 58% of temporal failures had the
+evidence SERVED but relative — the answering model can't do the arithmetic
+reliably; the store should carry it resolved.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from typing import Optional
+
+_MONTHS = "january february march april may june july august september october november december".split()
+_WEEKDAYS = "monday tuesday wednesday thursday friday saturday sunday".split()
+_WORD_NUMS = {"a": 1, "an": 1, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5,
+              "six": 6, "seven": 7, "eight": 8, "nine": 9, "ten": 10, "couple of": 2,
+              "few": 3}
+
+_ANCHOR_PATTERNS = [
+    "%d %B, %Y", "%d %B %Y", "%B %d, %Y", "%B %d %Y", "%Y-%m-%d", "%d/%m/%Y",
+]
+
+
+def parse_anchor(s: Optional[str]) -> Optional[_dt.date]:
+    """Parse a conversation timestamp like '8 May, 2023' into a date."""
+    if not s:
+        return None
+    s = s.strip()
+    # tolerate a leading time ("1:56 pm on 8 May, 2023")
+    if " on " in s:
+        s = s.split(" on ")[-1].strip()
+    for fmt in _ANCHOR_PATTERNS:
+        try:
+            return _dt.datetime.strptime(s, fmt).date()
+        except ValueError:
+            continue
+    m = re.search(r"(\d{1,2})\s+([A-Za-z]+),?\s+(\d{4})", s)
+    if m and m.group(2).lower() in _MONTHS:
+        return _dt.date(int(m.group(3)), _MONTHS.index(m.group(2).lower()) + 1,
+                        int(m.group(1)))
+    return None
+
+
+def _fmt_date(d: _dt.date) -> str:
+    return f"{_WEEKDAYS[d.weekday()].capitalize()}, {d.day} {_MONTHS[d.month - 1].capitalize()} {d.year}"
+
+
+def _fmt_month(d: _dt.date) -> str:
+    return f"{_MONTHS[d.month - 1].capitalize()} {d.year}"
+
+
+def _month_shift(d: _dt.date, months: int) -> _dt.date:
+    m = d.month - 1 + months
+    return _dt.date(d.year + m // 12, m % 12 + 1, 1)
+
+
+def resolve_relatives(text: str, anchor: Optional[_dt.date],
+                      max_annotations: int = 3) -> str:
+    """Annotate relative time expressions with computed absolutes, inline."""
+    if anchor is None or "[=" in text:
+        return text
+    count = 0
+
+    def ann(match_text: str, resolved: str) -> str:
+        nonlocal count
+        count += 1
+        return f"{match_text} [= {resolved}]"
+
+    def sub(pattern: str, resolver) -> None:
+        nonlocal text
+        def repl(m: re.Match) -> str:
+            if count >= max_annotations:
+                return m.group(0)
+            r = resolver(m)
+            return ann(m.group(0), r) if r else m.group(0)
+        text = re.sub(pattern, repl, text, flags=re.IGNORECASE)
+
+    # exact-day expressions
+    sub(r"\byesterday\b", lambda m: _fmt_date(anchor - _dt.timedelta(days=1)))
+    sub(r"\blast night\b", lambda m: _fmt_date(anchor - _dt.timedelta(days=1)))
+    sub(r"\b(today|tonight|this morning|this evening|this afternoon)\b",
+        lambda m: _fmt_date(anchor))
+    sub(r"\btomorrow\b", lambda m: _fmt_date(anchor + _dt.timedelta(days=1)))
+    # last/next <weekday>: the most recent such day strictly before (after) anchor
+    sub(r"\blast\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b",
+        lambda m: _fmt_date(anchor - _dt.timedelta(
+            days=((anchor.weekday() - _WEEKDAYS.index(m.group(1).lower())) % 7) or 7)))
+    sub(r"\bnext\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b",
+        lambda m: _fmt_date(anchor + _dt.timedelta(
+            days=((_WEEKDAYS.index(m.group(1).lower()) - anchor.weekday()) % 7) or 7)))
+    # periods — phrased the way LoCoMo golds phrase them
+    sub(r"\blast\s+week(end)?\b",
+        lambda m: f"the week{'end' if m.group(1) else ''} before {anchor.day} "
+                  f"{_MONTHS[anchor.month - 1].capitalize()} {anchor.year}")
+    sub(r"\bthis\s+week(end)?\b",
+        lambda m: f"the week{'end' if m.group(1) else ''} of {anchor.day} "
+                  f"{_MONTHS[anchor.month - 1].capitalize()} {anchor.year}")
+    sub(r"\blast\s+month\b", lambda m: _fmt_month(_month_shift(anchor, -1)))
+    sub(r"\bnext\s+month\b", lambda m: _fmt_month(_month_shift(anchor, 1)))
+    sub(r"\bthis\s+month\b", lambda m: _fmt_month(anchor))
+    sub(r"\blast\s+year\b", lambda m: str(anchor.year - 1))
+    sub(r"\bnext\s+year\b", lambda m: str(anchor.year + 1))
+    # "N days/weeks/months/years ago"
+    def ago(m: re.Match) -> Optional[str]:
+        raw = m.group(1).lower()
+        n = _WORD_NUMS.get(raw) or (int(raw) if raw.isdigit() else None)
+        if n is None:
+            return None
+        unit = m.group(2).lower()
+        if unit == "day":
+            return _fmt_date(anchor - _dt.timedelta(days=n))
+        if unit == "week":
+            return _fmt_date(anchor - _dt.timedelta(weeks=n))
+        if unit == "month":
+            return _fmt_month(_month_shift(anchor, -n))
+        return str(anchor.year - n)
+    sub(r"\b(\d+|a|an|one|two|three|four|five|six|seven|eight|nine|ten|few|couple of)"
+        r"\s+(day|week|month|year)s?\s+ago\b", ago)
+    return text