brainplug 0.4.0__py3-none-any.whl

brainplug/demo.py

@@ -0,0 +1,165 @@
+"""Synthetic history so anyone can try Brainplug without exporting anything.
+
+Chats, notes, documents and messages are generated from templates: none of it is real.
+"""
+
+from __future__ import annotations
+
+import random
+from datetime import datetime, timedelta, timezone
+
+from .sources import Item
+
+TOPICS = {
+    "python": {
+        "chat": ["Pandas groupby question", "Fix my Python loop", "Plot with matplotlib",
+                 "Read CSV in pandas", "Merge two dataframes", "Pandas pivot table"],
+        "note": ["Python cheat sheet", "Pandas tricks", "Data cleaning checklist"],
+        "mail": ["Python assignment group work", "Notebook for the data project"],
+        "words": ["python", "pandas", "dataframe", "groupby", "csv", "matplotlib", "loop",
+                  "function", "error", "column", "index", "merge", "plot", "numpy"],
+    },
+    "econometrics": {
+        "chat": ["OLS regression assumptions", "Interpret R squared", "Heteroskedasticity test",
+                 "Dummy variables in regression", "Panel data basics"],
+        "note": ["Econometrics lecture notes", "Regression formulas", "Exam summary econometrics"],
+        "mail": ["Question about the regression exercise", "Econometrics exam review"],
+        "words": ["regression", "ols", "coefficient", "variance", "residuals", "hypothesis",
+                  "significance", "estimator", "heteroskedasticity", "dummy", "model"],
+    },
+    "finance": {
+        "chat": ["How do index funds work", "Compound interest example", "ETF vs mutual fund",
+                 "Read a balance sheet", "Bond yields explained"],
+        "note": ["Investing principles", "Portfolio ideas", "Valuation notes"],
+        "mail": ["Investment club meeting", "Stock pitch feedback"],
+        "words": ["etf", "index", "fund", "interest", "portfolio", "stocks", "bonds", "yield",
+                  "balance", "sheet", "ebitda", "valuation", "returns", "risk"],
+    },
+    "printing": {
+        "chat": ["PLA vs PETG settings", "First layer not sticking", "Design a phone stand",
+                 "Calibrate 3D printer", "Print supports removal"],
+        "note": ["3D printer settings log", "Print ideas list", "Filament comparison"],
+        "mail": ["Filament order", "3D printed part for the lab"],
+        "words": ["printer", "pla", "petg", "layer", "nozzle", "filament", "supports", "stl",
+                  "slicer", "bed", "temperature", "infill", "print"],
+    },
+    "fitness": {
+        "chat": ["Push pull legs routine", "Protein intake per day", "Running plan 10k",
+                 "Gym routine for beginners", "Creatine questions"],
+        "note": ["Workout log", "Running progress", "Meal and protein targets"],
+        "mail": ["Gym membership renewal", "10k race registration"],
+        "words": ["workout", "routine", "protein", "gym", "running", "muscle", "sets", "reps",
+                  "training", "recovery", "squat", "cardio"],
+    },
+    "travel": {
+        "chat": ["3 days in Lisbon", "Greek islands itinerary", "Cheap flights tips",
+                 "Weekend in Porto", "Interrail route ideas"],
+        "note": ["Trip packing list", "Places to visit", "Summer trip budget"],
+        "mail": ["Hotel booking confirmation question", "Summer trip plan with friends"],
+        "words": ["trip", "itinerary", "flight", "hotel", "beach", "islands", "museum",
+                  "train", "budget", "days", "restaurants", "visit"],
+    },
+    "career": {
+        "chat": ["Improve my CV", "Internship cover letter", "LinkedIn headline ideas",
+                 "Prepare interview questions", "Networking message draft"],
+        "note": ["Internship applications tracker", "Interview answers", "Career goals"],
+        "mail": ["Internship application", "Thank you after the interview", "Coffee chat request"],
+        "words": ["cv", "internship", "linkedin", "interview", "cover", "letter", "recruiter",
+                  "application", "networking", "headline", "experience", "skills"],
+    },
+    "startup": {
+        "chat": ["Validate my startup idea", "Landing page copy", "Pricing strategy",
+                 "Pitch deck structure", "Find first users"],
+        "note": ["Startup idea journal", "User interview notes", "Launch checklist"],
+        "mail": ["Feedback on the landing page", "Intro to a potential user"],
+        "words": ["startup", "users", "mvp", "pricing", "landing", "page", "pitch", "deck",
+                  "customers", "growth", "idea", "market", "launch"],
+    },
+    "cooking": {
+        "chat": ["Easy pasta recipe", "Meal prep for the week", "Healthy breakfast ideas",
+                 "How to cook rice", "Quick dinner ideas"],
+        "note": ["Favourite recipes", "Weekly meal plan", "Shopping list staples"],
+        "mail": ["Dinner on Saturday", "Recipe you asked for"],
+        "words": ["recipe", "pasta", "chicken", "rice", "cook", "oven", "dinner", "breakfast",
+                  "ingredients", "meal", "prep", "minutes"],
+    },
+}
+
+# Relative weight of each topic over time (start -> end): some rise, some fade.
+TRENDS = {
+    "python": (1, 5), "econometrics": (3, 2), "finance": (1, 3), "printing": (0, 4),
+    "fitness": (3, 0.4), "travel": (2, 2), "career": (1, 4), "startup": (0, 3), "cooking": (2.5, 0),
+}
+SOURCES = [("chatgpt", "chat", 30), ("claude", "chat", 20), ("gemini", "chat", 8),
+           ("obsidian", "note", 16), ("notion", "note", 7), ("word", "note", 4), ("pdf", "note", 2),
+           ("gmail", "message", 8), ("whatsapp", "message", 5)]
+PEOPLE = ["Marta", "Study group", "Dani", "Family", "Lucía", "Football friends", "Pablo", "Flatmates"]
+FILLERS = ["can you explain", "how do I", "what is the best way to", "I am trying to understand",
+           "help me with", "quick question about", "why does", "give me an example of"]
+
+
+def generate(n: int = 600, seed: int = 7, end: datetime | None = None,
+             months: int = 18) -> list[Item]:
+    rng = random.Random(seed)
+    end = end or datetime(2026, 11, 10, tzinfo=timezone.utc)
+    start = end - timedelta(days=30 * months)
+    span = (end - start).total_seconds()
+    names = list(TOPICS)
+    notes_by_topic: dict[str, list[str]] = {k: [] for k in names}
+    items: list[Item] = []
+
+    def sentence(spec, extra, lo=4, hi=8):
+        vocab = spec["words"] + extra
+        return " ".join(rng.sample(vocab, k=min(len(vocab), rng.randint(lo, hi))))
+
+    stamps = sorted(rng.random() ** 0.55 for _ in range(n))  # usage grows over time
+    for i, t in enumerate(stamps):
+        created = start + timedelta(seconds=t * span)
+        hour = rng.choice([8, 9, 10, 11, 12, 13, 16, 17, 18, 19, 21, 22, 22, 23, 23, 0])
+        created = created.replace(hour=hour, minute=rng.randrange(60))
+        if t > 0.6 and rng.random() < 0.5:
+            weights = [TRENDS[k][1] for k in names]  # recent months follow the "end" mix
+        else:
+            weights = [TRENDS[k][0] + (TRENDS[k][1] - TRENDS[k][0]) * t + 0.15 for k in names]
+        topic = rng.choices(names, weights=weights)[0]
+        if topic == "cooking" and t > 0.68:  # an interest that was dropped...
+            topic = "python"
+        if topic == "startup" and t < 0.74:  # ...and one that only started recently
+            topic = "travel"
+        spec = TOPICS[topic]
+        other = rng.choice(names) if rng.random() < 0.12 else topic  # some items mix two topics
+        if (other == "cooking" and t > 0.68) or (other == "startup" and t < 0.74):
+            other = topic
+        extra = TOPICS[other]["words"][:10] if other != topic else []
+        source, kind, _ = rng.choices(SOURCES, weights=[s[2] for s in SOURCES])[0]
+
+        if kind == "chat":
+            turns = rng.choice([1, 1, 2, 2, 3, 4, 6, 9])
+            parts, lines, when = [], [], created
+            for _ in range(turns):
+                lines.append(f"{rng.choice(FILLERS)} {sentence(spec, extra)}?")
+                parts.append(when)
+                when += timedelta(minutes=rng.randint(1, 15))
+            items.append(Item(f"demo-{i}", rng.choice(spec["chat"]), created, source, "chat",
+                              "\n".join(lines), parts=parts, size=turns * 2))
+        elif kind == "note":
+            title = rng.choice(spec["note"])
+            links = []
+            if notes_by_topic[topic] and rng.random() < 0.7:
+                links.append(rng.choice(notes_by_topic[topic]))
+            if other != topic and notes_by_topic[other]:
+                links.append(rng.choice(notes_by_topic[other]))
+            text = ". ".join(sentence(spec, extra, 6, 11) for _ in range(rng.randint(2, 7)))
+            items.append(Item(f"demo-{i}", title, created, source, "note", text,
+                              links=links, tags=[topic]))
+            notes_by_topic[topic].append(title)
+        else:
+            replies = rng.choice([1, 1, 2, 3])
+            parts = [created + timedelta(hours=6 * j) for j in range(replies)]
+            text = ". ".join(f"hi, about the {sentence(spec, extra, 5, 9)}" for _ in range(replies))
+            title = rng.choice(PEOPLE) if source == "whatsapp" else rng.choice(spec["mail"])
+            items.append(Item(f"demo-{i}", title, created, source, "message",
+                              text, parts=parts, size=replies * (3 if source == "whatsapp" else 1)))
+
+    items.sort(key=lambda it: it.created)
+    return items

brainplug/export.py

@@ -0,0 +1,142 @@
+"""Write your record back as Markdown notes that Obsidian can open.
+
+Creates a ``Brainplug/`` folder with:
+
+* ``Brainplug.md``        an index of your topics
+* ``Topics/<topic>.md``    one map-of-content per topic, grouped by month
+* ``Items/<source>/…md``   one note per chat or email, with what you wrote
+                           and ``[[links]]`` to related items
+
+Notes that already live in your vault are linked by name, never copied.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from pathlib import Path
+
+from .analysis import SOURCE_NAMES
+from .sources import Item
+
+MAX_TEXT = 6000
+
+
+def safe_name(name: str, limit: int = 90) -> str:
+    name = re.sub(r'[\\/:*?"<>|#^\[\]]+', " ", name)
+    name = re.sub(r"\s+", " ", name).strip(" .")
+    return name[:limit].rstrip(" .") or "Untitled"
+
+
+def _slug(name: str) -> str:
+    return re.sub(r"[^\w]+", "-", name.lower(), flags=re.UNICODE).strip("-") or "topic"
+
+
+def export_vault(items: list[Item], payload: dict, out_dir: str | Path) -> int:
+    base = Path(out_dir) / "Brainplug"
+    topics, meta = payload["topics"], payload["items"]
+    used: set[str] = set()
+    names: dict[int, str] = {}
+    own: set[int] = set()  # items we write a note for
+    for i, item in enumerate(items):
+        if item.source in ("obsidian", "notes"):
+            names[i] = safe_name(item.title)  # already a note in the vault
+            continue
+        name = safe_name(f"{item.title} ({meta[i]['d']})")
+        n = 2
+        while name.lower() in used:
+            name = safe_name(f"{item.title} ({meta[i]['d']}) {n}")
+            n += 1
+        used.add(name.lower())
+        names[i] = name
+        own.add(i)
+
+    related: dict[int, list[int]] = defaultdict(list)
+    for a, b, _w, _kind in payload["edges"]:
+        related[a].append(b)
+        related[b].append(a)
+
+    written = 0
+    for i in sorted(own):
+        item, topic = items[i], topics[meta[i]["k"]]
+        folder = base / "Items" / SOURCE_NAMES.get(item.source, item.source.title())
+        folder.mkdir(parents=True, exist_ok=True)
+        text = item.text[:MAX_TEXT] + (" […]" if len(item.text) > MAX_TEXT else "")
+        lines = [
+            "---", f"date: {meta[i]['d']}", f"source: {item.source}", f"type: {item.kind}",
+            f'topic: "{topic["name"]}"', f"tags: [brainplug, brainplug/{_slug(topic['name'])}]",
+            "---", "", f"# {item.title}", "", f"Topic: [[{safe_name(topic['name'])}]]", "",
+            "## What I wrote", "", text, "",
+        ]
+        if related[i]:
+            lines += ["## Related", ""] + [f"- [[{names[j]}]]" for j in related[i][:8]] + [""]
+        (folder / f"{names[i]}.md").write_text("\n".join(lines), encoding="utf-8")
+        written += 1
+
+    (base / "Topics").mkdir(parents=True, exist_ok=True)
+    for topic in topics:
+        by_month: dict[str, list[int]] = defaultdict(list)
+        for i, m in enumerate(meta):
+            if m["k"] == topic["id"]:
+                by_month["No date" if m["u"] else m["d"][:7]].append(i)
+        lines = ["---", "type: topic", f"items: {topic['count']}", "tags: [brainplug]", "---", "",
+                 f"# {topic['name']}", "", f"Key terms: {', '.join(topic['terms'])}", ""]
+        for month in sorted(by_month, reverse=True):
+            lines += [f"## {month}", ""]
+            lines += [f"- [[{names[i]}]] · {SOURCE_NAMES.get(items[i].source, items[i].source)}"
+                      f" · {meta[i]['d']}" for i in reversed(by_month[month])]
+            lines.append("")
+        (base / "Topics" / f"{safe_name(topic['name'])}.md").write_text("\n".join(lines), encoding="utf-8")
+        written += 1
+
+    numbers = payload["numbers"]
+    index = ["# Brainplug", "", f"{numbers['items']} items · {numbers['first']} → {numbers['last']}", "",
+             "## Topics", ""]
+    index += [f"- [[{safe_name(t['name'])}]] · {t['count']} items ({round(t['share'] * 100)}%)" for t in topics]
+    (base / "Brainplug.md").write_text("\n".join(index) + "\n", encoding="utf-8")
+    return written + 1
+
+
+# --------------------------------------------------------------------------- #
+# research dataset
+# --------------------------------------------------------------------------- #
+_REDACT = [
+    (re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+"), "[email]"),
+    (re.compile(r"(?:https?://|www\.)\S+"), "[url]"),
+    (re.compile(r"\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){3,7}(?: ?[A-Z0-9]{1,3})?\b"), "[iban]"),
+    # 9 digits or more, with the usual separators (a date such as 2025-03-04 has only 8)
+    (re.compile(r"(?<!\w)\+?\d[\d ().-]{7,}\d(?!\w)"),
+     lambda m: "[phone]" if sum(c.isdigit() for c in m.group()) >= 9 else m.group()),
+    (re.compile(r"\b\d{5,}\b"), "[number]"),
+    (re.compile(r"(?<!\w)@\w{2,}"), "[handle]"),
+]
+
+
+def redact(text: str) -> str:
+    """Mask the obvious identifiers: emails, links, phone and account numbers,
+    long numbers and @handles. Names and anything else you wrote stay as they are."""
+    for pattern, label in _REDACT:
+        text = pattern.sub(label, text)
+    return text
+
+
+def export_dataset(items: list[Item], payload: dict, out: str | Path) -> int:
+    """Write your own words as a JSON Lines file you could hand to a researcher.
+
+    One line per item: month, source, kind, topic, word count and the redacted
+    text. Titles, exact dates and ids are left out. This is **best-effort
+    redaction, not anonymisation**: read the file before you share it.
+    """
+    import json
+
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    topics, meta = payload["topics"], payload["items"]
+    with open(out, "w", encoding="utf-8") as fh:
+        for i, item in enumerate(items):
+            fh.write(json.dumps({
+                "n": i + 1, "month": meta[i]["d"][:7] if not meta[i]["u"] else None,
+                "source": item.source, "kind": item.kind, "topic": topics[meta[i]["k"]]["name"],
+                "words": item.words, "text": redact(item.text[:MAX_TEXT * 4]),
+            }, ensure_ascii=False) + "\n")
+    return len(items)

brainplug/memory.py

@@ -0,0 +1,356 @@
+"""A memory your AI can read and write: plain Markdown inside your vault.
+
+    <vault>/Brainplug/About me.md     what every assistant should know about you (you write it)
+    <vault>/Brainplug/Memory/*.md     one note per thing an assistant was asked to remember
+
+    <vault>/Brainplug/Excluded.md     what you asked to leave out of the brain (one line each)
+
+Every memory is an ordinary note: open it in Obsidian, edit it, move it, delete
+it. Nothing is hidden and nothing leaves the folder. An assistant can add
+memories and archive them; it never edits "About me" and never deletes a file.
+
+What an assistant asks to keep as a standing preference (pinned, or of kind
+"preference") waits for your approval (``pinned: pending``) before it becomes
+part of every briefing, so a web page that tricked one assistant cannot plant
+instructions for all of them.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+FOLDER = "Brainplug"
+MEMORY = "Memory"
+PROFILE = "About me.md"
+EXCLUDED = "Excluded.md"
+TOPIC_NAMES = "Topic names.md"
+PENDING = "pending"
+KINDS = ("note", "fact", "preference", "decision", "project")
+MAX_TEXT = 8000
+TEMPLATE_MARK = "brainplug: fill this in"
+
+_TEMPLATES = {
+    "en": """---
+created: {today}
+---
+# About me
+
+<!-- {mark}. Assistants read this note at the start of a conversation, so keep it short. -->
+
+- Name:
+- What I do:
+- What I am working on now:
+- How I like answers (language, length, tone):
+""",
+    "es": """---
+created: {today}
+---
+# Sobre mí
+
+<!-- {mark}. Los asistentes leen esta nota al empezar una conversación, así que mejor breve. -->
+
+- Nombre:
+- A qué me dedico:
+- En qué estoy trabajando ahora:
+- Cómo me gustan las respuestas (idioma, longitud, tono):
+""",
+}
+
+
+def brain_dir(vault: str | Path) -> Path:
+    return Path(vault).expanduser() / FOLDER
+
+
+def init(vault: str | Path, lang: str = "en") -> Path:
+    """Create the Brainplug folder in a vault (or any folder). Existing notes are left alone."""
+    base = brain_dir(vault)
+    (base / MEMORY).mkdir(parents=True, exist_ok=True)
+    profile = base / PROFILE
+    if not profile.exists():
+        profile.write_text(_TEMPLATES["es" if lang == "es" else "en"].format(
+            today=datetime.now().strftime("%Y-%m-%d"), mark=TEMPLATE_MARK), encoding="utf-8")
+    return base
+
+
+def _split(text: str) -> tuple[dict, str]:
+    """Frontmatter (flat ``key: value`` pairs) and body of a note."""
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("\n---", 3)
+    if end < 0:
+        return {}, text
+    meta = {}
+    for line in text[3:end].splitlines():
+        key, sep, value = line.partition(":")
+        if sep and key.strip() and not key[:1].isspace():
+            meta[key.strip().lower()] = value.strip()
+    return meta, text[end + 4:].lstrip("\n")
+
+
+def profile(vault: str | Path) -> str:
+    """Your "About me" note as plain text, or "" while it is still the empty template."""
+    path = brain_dir(vault) / PROFILE
+    if not path.exists():
+        return ""
+    _, body = _split(path.read_text(encoding="utf-8", errors="ignore"))
+    if TEMPLATE_MARK in body:
+        filled = [l for l in body.splitlines() if re.match(r"^- [^:]+:\s*\S", l)]
+        if not filled:
+            return ""
+    body = re.sub(r"<!--.*?-->", "", body, flags=re.S)
+    lines = [l.rstrip() for l in body.splitlines() if l.strip() and not re.match(r"^- [^:]+:\s*$", l)]
+    return "\n".join(lines).strip()
+
+
+def _safe(name: str, limit: int = 70) -> str:
+    name = re.sub(r'[\\/:*?"<>|#^\[\]\x00-\x1f]+', " ", name)
+    name = re.sub(r"\s+", " ", name).strip(" .")
+    return name[:limit].rstrip(" .")
+
+
+def _tag(tag: str) -> str:
+    return re.sub(r"[^\w/-]+", "-", tag.strip().lstrip("#"), flags=re.UNICODE).strip("-").lower()
+
+
+def remember(vault: str | Path, text: str, title: str = "", kind: str = "note", tags: list[str] | tuple = (),
+             source: str = "", pin: bool = False, when: datetime | None = None, approved: bool = True,
+             replaces: str = "") -> Path:
+    """Save one memory as a note in ``Brainplug/Memory`` and return its path.
+
+    ``approved=False`` is for memories an assistant saves: a pinned one, or a
+    preference, is marked ``pinned: pending`` until the person approves it.
+    ``replaces`` names the memory note this one corrects (see ``supersede``)."""
+    text = " ".join(str(text).split()) if "\n" not in str(text).strip() else str(text).strip()
+    if not text:
+        raise ValueError("There is nothing to remember: the text is empty.")
+    text = text[:MAX_TEXT]
+    kind = kind if kind in KINDS else "note"
+    when = when or datetime.now().astimezone()
+    folder = init(vault) / MEMORY
+    named = bool(_safe(title))
+    title = _safe(title) or _safe(" ".join(text.split()[:9])) or "Memory"
+    stem = f"{when:%Y-%m-%d} {title}"
+    labels = ["brainplug/memory", f"brainplug/{kind}", *[t for t in map(_tag, tags) if t]]
+    head = ["---", f"created: {when.isoformat(timespec='seconds')}", f"kind: {kind}"]
+    if _safe(source):
+        head.append(f"saved_by: {_safe(source, 40)}")
+    if (pin or kind == "preference") and not approved:
+        head.append(f"pinned: {PENDING}")  # a standing preference waits for the person's yes
+    elif pin:
+        head.append("pinned: true")
+    if _safe(replaces, 200):
+        head.append(f"replaces: {_safe(replaces, 200)}")
+    head += [f"tags: [{', '.join(dict.fromkeys(labels))}]", "---", ""]
+    head += [f"# {title}", "", text, ""] if named else [text, ""]  # an untitled memory is named after its own words
+    n = 1
+    while True:  # never overwrite a note, even when two assistants save at the same moment
+        path = folder / (f"{stem}.md" if n == 1 else f"{stem} {n}.md")
+        try:
+            with open(path, "x", encoding="utf-8") as fh:
+                fh.write("\n".join(head))
+            return path
+        except FileExistsError:
+            n += 1
+
+
+def memories(vault: str | Path) -> list[dict]:
+    """Every memory that has not been archived, newest first."""
+    folder = brain_dir(vault) / MEMORY
+    out = []
+    for path in sorted(folder.glob("*.md")) if folder.exists() else []:
+        meta, body = _split(path.read_text(encoding="utf-8", errors="ignore"))
+        if meta.get("archived", "").lower() == "true":
+            continue
+        body = re.sub(r"^# .*\n+", "", body, count=1).strip()
+        pinned = meta.get("pinned", "").lower()
+        out.append({"path": path, "name": path.stem, "created": meta.get("created", ""), "kind": meta.get("kind", "note"),
+                    "pinned": pinned == "true", "pending": pinned == PENDING, "by": meta.get("saved_by", ""),
+                    "text": body})
+    out.sort(key=lambda m: (m["created"], m["name"]), reverse=True)
+    return out
+
+
+def _find(vault: str | Path, name: str) -> Path | None:
+    folder = brain_dir(vault) / MEMORY
+    wanted = _safe(Path(str(name)).stem, 200).lower()
+    for path in sorted(folder.glob("*.md")) if folder.exists() and wanted else []:
+        if path.stem.lower() == wanted:
+            return path
+    return None
+
+
+def _update(path: Path, changes: dict[str, str | None]) -> None:
+    """Set (or, with None, remove) flat frontmatter fields and leave the rest of the note as it is."""
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    end = text.find("\n---", 3) if text.startswith("---") else -1
+    head = text[3:end].strip("\n").split("\n") if end >= 0 else []
+    rest = text[end + 4:] if end >= 0 else "\n" + text
+    out, done = [], set()
+    for line in head:
+        key = line.partition(":")[0].strip().lower()
+        if key in changes and not line[:1].isspace():
+            if changes[key] is not None and key not in done:
+                out.append(f"{key}: {changes[key]}")
+                done.add(key)
+            continue
+        out.append(line)
+    out += [f"{k}: {v}" for k, v in changes.items() if v is not None and k not in done]
+    path.write_text("---\n" + "\n".join(line for line in out if line.strip()) + "\n---" + rest, encoding="utf-8")
+
+
+def forget(vault: str | Path, name: str) -> Path | None:
+    """Archive a memory by its note name. The note stays in the vault, marked ``archived: true``,
+    and is no longer read; delete the file yourself if you want it gone."""
+    path = _find(vault, name)
+    if path is not None:
+        _update(path, {"archived": "true"})
+    return path
+
+
+def supersede(vault: str | Path, old: str, new: str) -> Path | None:
+    """Archive memory ``old`` because memory ``new`` corrects it; each note names the other."""
+    path = _find(vault, old)
+    if path is not None:
+        _update(path, {"archived": "true", "superseded_by": _safe(new, 200)})
+    return path
+
+
+def pending(vault: str | Path) -> list[dict]:
+    """Memories assistants saved as standing preferences that still wait for the person's approval."""
+    return [m for m in memories(vault) if m["pending"]]
+
+
+def approve(vault: str | Path, name: str) -> Path | None:
+    """The person agrees: the memory becomes part of every briefing."""
+    path = _find(vault, name)
+    if path is not None:
+        _update(path, {"pinned": "true"})
+        replaced = _split(path.read_text(encoding="utf-8", errors="ignore"))[0].get("replaces")
+        if replaced:  # the memory it corrects is archived only now
+            supersede(vault, replaced, path.stem)
+    return path
+
+
+# ---------------------------------------------------------------- exclusions
+_EXCLUDED_HEAD = """---
+kind: brainplug-exclusions
+---
+# Left out of Brainplug
+
+Everything listed here stays out of your brain: the map, search and what assistants read.
+Delete a line to bring it back.
+
+"""
+_EXCLUDED_LINE = re.compile(r"^\s*[-*]\s+(source:\s*)?`([^`]+)`")
+
+
+def exclusions(vault: str | Path) -> tuple[set[str], set[str]]:
+    """The item ids and the sources listed in ``Brainplug/Excluded.md``."""
+    path = brain_dir(vault) / EXCLUDED
+    ids: set[str] = set()
+    sources: set[str] = set()
+    if path.exists():
+        for line in path.read_text(encoding="utf-8", errors="ignore").splitlines():
+            m = _EXCLUDED_LINE.match(line)
+            if m:
+                (sources if m.group(1) else ids).add(m.group(2).strip())
+    return ids, sources
+
+
+def exclude(vault: str | Path, item_id: str = "", title: str = "", source: str = "", by: str = "",
+            reason: str = "") -> Path:
+    """Add one line to ``Brainplug/Excluded.md``: an item, or a whole source, to leave out."""
+    item_id, source = item_id.replace("`", ""), re.sub(r"[^a-z0-9]", "", source.lower())
+    if not item_id and not source:
+        raise ValueError("Say which item or which source to leave out.")
+    path = init(vault) / EXCLUDED
+    if not path.exists():
+        path.write_text(_EXCLUDED_HEAD, encoding="utf-8")
+    line = f"- source: `{source}`" if source else f"- `{item_id}` · {_safe(title, 80) or 'untitled'}"
+    line += f" · {datetime.now():%Y-%m-%d}" + (f" · by {_safe(by, 40)}" if _safe(by) else "")
+    line += f": {' '.join(str(reason).split())[:200]}" if str(reason).strip() else ""
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(line + "\n")
+    return path
+
+
+# --------------------------------------------------------------- topic names
+_NAMES_HEAD = """---
+kind: brainplug-topic-names
+---
+# Topic names
+
+Brainplug names a topic after its strongest words. A name here replaces that, for the topic
+whose words match. Edit or delete a line any time.
+
+"""
+_NAME_LINE = re.compile(r"^\s*[-*]\s+\*\*(.+?)\*\*\s+·\s+(.+?)\s*$")
+_NAME_OK = re.compile(r"^[\w][\w\s&'’.,()/+-]*$", re.UNICODE)
+
+
+def clean_topic_name(name: str) -> str:
+    """A short label: up to 5 words and 40 characters of letters, digits and simple punctuation."""
+    name = " ".join(str(name).split())
+    if not name or len(name) > 40 or len(name.split()) > 5 or not _NAME_OK.match(name):
+        raise ValueError("A topic name is 1 to 5 words (40 characters at most), letters, digits and simple punctuation.")
+    return name
+
+
+def topic_names(vault: str | Path) -> list[tuple[str, list[str]]]:
+    """The names in ``Brainplug/Topic names.md``, each with the words of the topic it names."""
+    path = brain_dir(vault) / TOPIC_NAMES
+    out = []
+    for line in path.read_text(encoding="utf-8", errors="ignore").splitlines() if path.exists() else []:
+        m = _NAME_LINE.match(line)
+        if m:
+            out.append((m.group(1).strip(), [w.strip().lower() for w in m.group(2).split(",") if w.strip()]))
+    return out
+
+
+def name_topic(vault: str | Path, name: str, terms: list[str]) -> Path:
+    """Save a name for the topic with these words, replacing any name it had."""
+    name, words = clean_topic_name(name), [w.lower() for w in terms if w]
+    if not words:
+        raise ValueError("That topic has no words to remember its name by.")
+    kept = [(n, t) for n, t in topic_names(vault) if len(set(t) & set(words)) * 2 < max(1, len(t))]
+    path = init(vault) / TOPIC_NAMES
+    lines = [f"- **{n}** · {', '.join(t)}" for n, t in kept + [(name, words)]]
+    path.write_text(_NAMES_HEAD + "\n".join(lines) + "\n", encoding="utf-8")
+    return path
+
+
+# ------------------------------------------------------------- About me draft
+_DRAFT = {
+    "en": {"about": "What I write about most", "now": "What I am working on now", "where": "Where I write",
+           "when": "When I write", "at": "mostly on {day}s, around {hour}:00",
+           "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
+           "mark": "a draft from your writing, {d}: check it, fill in the rest and delete what is wrong"},
+    "es": {"about": "Sobre lo que más escribo", "now": "En qué estoy trabajando ahora", "where": "Dónde escribo",
+           "when": "Cuándo escribo", "at": "sobre todo los {day}, hacia las {hour}:00",
+           "days": ["lunes", "martes", "miércoles", "jueves", "viernes", "sábados", "domingos"],
+           "mark": "un borrador a partir de lo que escribes, {d}: revísalo, completa el resto y borra lo que no sea cierto"},
+}
+
+
+def draft_profile(vault: str | Path, payload: dict) -> tuple[Path, str, bool]:
+    """A draft of "About me" from what the analysis found. Written into the note only while it
+    is still the empty template; returns (path, draft, written)."""
+    base = init(vault)
+    path = base / PROFILE
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    t = _DRAFT["es" if "# Sobre mí" in text else "en"]
+    topics, n, review = payload["topics"], payload["numbers"], payload["review"]
+    rising = [topics[x["k"]]["name"] for x in review["rising"][:3]]
+    lines = [(t["about"], ", ".join(x["name"] for x in topics[:4])),
+             (t["now"], ", ".join(rising) or ", ".join(x["name"] for x in topics[:2])),
+             (t["where"], ", ".join(s["name"] for s in n["sources"][:4])),
+             (t["when"], t["at"].format(day=t["days"][n["busiest_weekday"]], hour=n["busiest_hour"]))]
+    draft = "\n".join(f"- {k}: {v}" for k, v in lines if v)
+    if profile(vault):
+        return path, draft, False  # yours already: never overwritten
+    body = re.sub(rf"(?m)^- {re.escape(t['now'])}:[ \t]*\n?", "", text).rstrip("\n")
+    path.write_text(f"{body}\n\n<!-- {t['mark'].format(d=datetime.now().strftime('%Y-%m-%d'))} -->\n{draft}\n",
+                    encoding="utf-8")
+    return path, draft, True