gnosion 0.2.0__py3-none-any.whl

gnosion/__init__.py

@@ -0,0 +1,14 @@
+"""Gnosion — a portable, self-improving cognitive engine.
+
+Pluggable cognition heads (vision / text / design / tabular / memory) that learn
+from every input, guarded so they never regress or memorise junk, and exportable
+as one portable .gnosion file you can import into any project.
+
+Zero required dependencies (pure-Python core); optional extras:
+  pip install "gnosion[embed]"  -> fastembed ONNX embeddings (real semantic quality)
+  pip install "gnosion[ml]"     -> numpy/scikit-learn acceleration
+"""
+from .core import Gnosion
+
+__version__ = "0.2.0"
+__all__ = ["Gnosion", "__version__"]

gnosion/agent.py

@@ -0,0 +1,190 @@
+"""Universal coding-agent memory — a full agent-memory model usable by ANY agent
+(Claude Code, Cursor, Windsurf, Cline, Aider, or your own scripts).
+
+It persists into one portable `.gnosion` in the repo (`.gnosion/project.gnosion`) and
+covers the standard agent-memory types:
+
+  fact         world/semantic facts
+  entity       facts ABOUT a subject — the user, the project, the environment
+  decision     choices made (and why)
+  convention   how we do things here
+  structure    system/architecture notes
+  bug          bugs + their fixes
+  preference   user/team preferences
+  experience   EPISODIC: "did X -> got Y" events, timestamped (experience tracking)
+  observation  raw things noticed in the environment
+  skill        PROCEDURAL: named how-to procedures the agent can recall + follow;
+               fully user-addable (add_skill)
+
+Recall matches shared WORDS by default (zero-dep); `pip install "gnosion[embed]"` +
+`GNOSION_SEMANTIC=1` upgrades it to semantic (paraphrase) recall.
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import List, Optional
+
+from .core import Gnosion
+
+# every memory type is a semantic memory domain
+KINDS = ["fact", "entity", "decision", "convention", "structure", "bug",
+         "preference", "experience", "observation", "skill"]
+ENTITY_SUBJECTS = ["user", "project", "environment", "team", "domain"]
+_DEFAULT_REL = os.path.join(".gnosion", "project.gnosion")
+
+
+def _domains():
+    return [{"name": k, "head": "memory", "modality": "text"} for k in KINDS] + \
+           [{"name": "all", "head": "memory", "modality": "text"}]
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+class AgentMemory:
+    """Repo-scoped, agent-agnostic project memory backed by a portable .gnosion."""
+
+    def __init__(self, root: str = ".", path: Optional[str] = None, semantic: Optional[bool] = None):
+        if semantic is None:
+            semantic = os.environ.get("GNOSION_SEMANTIC", "") in ("1", "true", "yes")
+        self.root = root
+        self.path = path or os.path.join(root, _DEFAULT_REL)
+        if os.path.exists(self.path):
+            self.bx = Gnosion.load(self.path)
+            for d in _domains():                       # add any new kinds to old files
+                if d["name"] not in self.bx.domains:
+                    self.bx.add_domain(d["name"], d["head"], d["modality"])
+        else:
+            self.bx = Gnosion(prefer_fastembed=semantic, domains=_domains())
+
+    # ---- generic write
+    def remember(self, text: str, kind: str = "fact", subject: Optional[str] = None,
+                 tags: Optional[list] = None, meta: Optional[dict] = None, save: bool = True) -> dict:
+        kind = kind if kind in KINDS else "fact"
+        m = {"kind": kind, "ts": _now()}
+        if subject:
+            m["subject"] = subject
+        if tags:
+            m["tags"] = list(tags)
+        if meta:
+            m.update(meta)
+        self.bx.remember(kind, text, text, meta=m)
+        self.bx.remember("all", text, text, meta=m)
+        if save:
+            self.save()
+        return {"ok": True, "kind": kind, "stored": text[:100]}
+
+    note = remember  # alias
+
+    # ---- typed helpers ---------------------------------------------------------
+    def fact(self, text: str, subject: Optional[str] = None, **kw) -> dict:
+        return self.remember(text, kind="fact", subject=subject, **kw)
+
+    def about(self, subject: str, text: str, **kw) -> dict:
+        """A fact ABOUT the user / project / environment (an entity)."""
+        return self.remember(text, kind="entity", subject=subject, **kw)
+
+    def experience(self, action: str, outcome: Optional[str] = None, tags: Optional[list] = None,
+                   **kw) -> dict:
+        """Episodic memory: record that an action led to an outcome (experience tracking)."""
+        text = action if not outcome else f"{action} -> {outcome}"
+        return self.remember(text, kind="experience", tags=tags,
+                             meta={"action": action, "outcome": outcome}, **kw)
+
+    def observe(self, text: str, tags: Optional[list] = None, **kw) -> dict:
+        """Raw observation noticed in the environment."""
+        return self.remember(text, kind="observation", tags=tags, **kw)
+
+    def add_skill(self, name: str, when_to_use: str, how: str, save: bool = True) -> dict:
+        """Add a user-defined SKILL: a named procedure the agent recalls and follows.
+        (Gnosion stores/serves it; the agent executes it — it isn't code Gnosion runs.)"""
+        value = f"SKILL: {name}\nWhen to use: {when_to_use}\nHow: {how}"
+        # index on name + when-to-use so it's found by task description
+        self.bx.remember("skill", f"{name}. {when_to_use}", value,
+                         meta={"kind": "skill", "name": name, "when": when_to_use,
+                               "how": how, "ts": _now()})
+        if save:
+            self.save()
+        return {"ok": True, "skill": name}
+
+    def knowledge_domains(self) -> List[str]:
+        """Custom knowledge domains fed via `gns feed` (marketing/seo/…) — every memory
+        domain that isn't a built-in agent-memory kind or the 'all' mirror."""
+        from .heads import MemoryHead
+        skip = set(KINDS) | {"all"}
+        return [n for n, d in self.bx.domains.items()
+                if n not in skip and isinstance(d.head, MemoryHead)]
+
+    # ---- read ------------------------------------------------------------------
+    def recall(self, query: str, kind: Optional[str] = None, k: int = 5,
+               min_sim: float = 0.30) -> List[dict]:
+        """Most relevant memories for a query. `kind` restricts scope; else all kinds
+        AND any fed knowledge domains."""
+        scopes = KINDS + self.knowledge_domains()
+        if kind and (kind in KINDS or kind in self.bx.domains):
+            hits = self.bx.search(kind, query, k=k, min_sim=min_sim)
+            for h in hits:
+                h["kind"] = kind
+            return hits
+        merged: List[dict] = []
+        for kk in scopes:
+            for h in self.bx.search(kk, query, k=k, min_sim=min_sim):
+                h["kind"] = kk
+                merged.append(h)
+        seen, out = set(), []
+        for h in sorted(merged, key=lambda x: x["similarity"], reverse=True):
+            if h["value"] in seen:
+                continue
+            seen.add(h["value"]); out.append(h)
+        return out[:k]
+
+    def recall_skill(self, task: str, k: int = 3, min_sim: float = 0.30) -> List[dict]:
+        """Which skill(s) apply to a task."""
+        return self.bx.search("skill", task, k=k, min_sim=min_sim)
+
+    def skills(self) -> List[dict]:
+        d = self.bx.domains.get("skill")
+        return [{"name": e["meta"].get("name"), "when": e["meta"].get("when"),
+                 "how": e["meta"].get("how")} for e in (d.head.entries if d else [])]
+
+    def about_subject(self, subject: str, k: int = 10) -> List[dict]:
+        """Everything remembered about a subject (user/project/environment)."""
+        d = self.bx.domains.get("entity")
+        return [{"value": e["value"], "meta": e["meta"]}
+                for e in (d.head.entries if d else []) if e["meta"].get("subject") == subject]
+
+    def briefing(self, k_per_kind: int = 3) -> str:
+        """Session-start briefing: entity facts, decisions, conventions, structure,
+        preferences, and available skills — to load into an agent's context."""
+        lines = []
+        for kk in ("entity", "decision", "convention", "structure", "preference"):
+            d = self.bx.domains.get(kk)
+            recent = (d.head.entries[-k_per_kind:] if d and d.head.entries else [])
+            if recent:
+                lines.append(f"## {kk.title()}")
+                lines += [f"- {e['value']}" for e in recent]
+        sk = self.skills()
+        if sk:
+            lines.append("## Skills available")
+            lines += [f"- {s['name']}: {s['when']}" for s in sk]
+        return "\n".join(lines) if lines else "(no project memory yet)"
+
+    def stats(self) -> dict:
+        s = {"path": self.path, "kinds": {}}
+        for kk in KINDS:
+            d = self.bx.domains.get(kk)
+            s["kinds"][kk] = len(d.head.entries) if d else 0
+        s["total"] = sum(s["kinds"].values())
+        return s
+
+    def save(self) -> str:
+        os.makedirs(os.path.dirname(os.path.abspath(self.path)) or ".", exist_ok=True)
+        out = self.bx.export(self.path)
+        try:                                    # keep the global project registry live
+            from . import registry
+            registry.record(self.root, self.stats())
+        except Exception:  # noqa: BLE001
+            pass
+        return out

gnosion/artifact.py

@@ -0,0 +1,64 @@
+"""The portable .gnosion artifact — one file that holds the whole brain (all domains,
+learned samples, memories, centroids, config). Pure stdlib (json + zip + gzip).
+
+    bx.export("company.gnosion")      # -> a single portable file
+    Gnosion.load("company.gnosion")    # import into any project / machine
+
+Layout inside the zip:
+    manifest.json   — version, dim, embedder ids, per-domain summary (human-readable)
+    brain.json.gz   — the full serialized brain (gzip-compressed)
+"""
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import time
+import zipfile
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core import Gnosion
+
+MAGIC = "gnosion"
+FORMAT = 1
+
+
+def export_brain(brain: "Gnosion", path: str) -> str:
+    if not path.endswith(".gnosion"):
+        path += ".gnosion"
+    data = brain.to_dict()
+    manifest = {
+        "magic": MAGIC, "format": FORMAT, "gnosion_version": brain.VERSION,
+        "dim": brain.dim, "created_at": int(time.time()),
+        "domains": [{"name": d["name"], "head": d["head"], "modality": d["modality"],
+                     "embedder": d["embedder"],
+                     "size": len(d["state"].get("samples", d["state"].get("entries", [])))}
+                    for d in data["domains"]],
+    }
+    os.makedirs(os.path.dirname(os.path.abspath(path)) or ".", exist_ok=True)
+    tmp = path + ".tmp"
+    with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("manifest.json", json.dumps(manifest, indent=2))
+        z.writestr("brain.json.gz", gzip.compress(json.dumps(data).encode("utf-8")))
+    os.replace(tmp, path)
+    return path
+
+
+def load_brain(path: str) -> "Gnosion":
+    from .core import Gnosion
+    with zipfile.ZipFile(path, "r") as z:
+        names = set(z.namelist())
+        if "brain.json.gz" in names:
+            data = json.loads(gzip.decompress(z.read("brain.json.gz")).decode("utf-8"))
+        elif "brain.json" in names:                      # uncompressed fallback
+            data = json.loads(z.read("brain.json").decode("utf-8"))
+        else:
+            raise ValueError("not a valid .gnosion file (no brain payload)")
+    return Gnosion.from_dict(data)
+
+
+def inspect(path: str) -> dict:
+    """Read just the manifest — quick peek without loading the whole brain."""
+    with zipfile.ZipFile(path, "r") as z:
+        return json.loads(z.read("manifest.json").decode("utf-8"))

gnosion/cli.py

@@ -0,0 +1,167 @@
+"""gnosion CLI —  `gnosion <command>`.
+
+Low-level (explicit .gnosion file):
+  gns inspect  brain.gnosion                         peek at a .gnosion file
+  gns stats    brain.gnosion                         full stats
+  gns learn    brain.gnosion text "reset password" --label account
+  gns train    brain.gnosion [--domain text]
+  gns predict  brain.gnosion text "how to log in"
+  gns recall   brain.gnosion design "how should we do auth"
+  gns new      brain.gnosion                         create an empty brain
+
+Universal agent memory (repo-scoped ./.gnosion/project.gnosion — for ANY coding agent):
+  gns note   "we use JWT in an httpOnly cookie" --kind decision
+  gns ask    "how should we do auth"  [--kind decision] [--k 5]
+  gns brief                                          session-start briefing
+  gns mem                                            memory stats
+  gns mcp                                            run the MCP server (stdio)
+
+Files are created on first write. Zero deps.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def _load_or_new(path: str):
+    from .core import Gnosion
+    if os.path.exists(path):
+        return Gnosion.load(path)
+    return Gnosion()
+
+
+def main(argv=None) -> int:
+    from . import __version__
+    p = argparse.ArgumentParser(prog="gns", description="Portable self-improving brain")
+    p.add_argument("--version", "-V", action="version", version=f"gns {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add(name, needs_domain=True, needs_text=False):
+        sp = sub.add_parser(name)
+        sp.add_argument("path")
+        if needs_domain:
+            sp.add_argument("domain", nargs="?")
+        if needs_text:
+            sp.add_argument("text")
+        return sp
+
+    add("new", needs_domain=False)
+    add("inspect", needs_domain=False)
+    add("stats", needs_domain=False)
+    lp = add("learn", needs_text=True); lp.add_argument("--label"); lp.add_argument("--value")
+    tp = sub.add_parser("train"); tp.add_argument("path"); tp.add_argument("--domain")
+    add("predict", needs_text=True)
+    add("recall", needs_text=True)
+
+    # ---- universal agent-memory commands (repo-scoped ./.gnosion/project.gnosion) ----
+    npn = sub.add_parser("note"); npn.add_argument("text")
+    npn.add_argument("--kind", default="fact"); npn.add_argument("--subject")
+    npn.add_argument("--root", default=".")
+    ask = sub.add_parser("ask"); ask.add_argument("query")
+    ask.add_argument("--kind"); ask.add_argument("--k", type=int, default=5); ask.add_argument("--root", default=".")
+    bpn = sub.add_parser("brief"); bpn.add_argument("--root", default=".")
+    mpn = sub.add_parser("mem"); mpn.add_argument("--root", default=".")
+    mcpn = sub.add_parser("mcp"); mcpn.add_argument("--root", default=".")
+    obs = sub.add_parser("observe"); obs.add_argument("text"); obs.add_argument("--root", default=".")
+    exp = sub.add_parser("experience"); exp.add_argument("action"); exp.add_argument("--outcome"); exp.add_argument("--root", default=".")
+    sk = sub.add_parser("skill"); sk.add_argument("name"); sk.add_argument("--when", required=True)
+    sk.add_argument("--how", required=True); sk.add_argument("--root", default=".")
+    skl = sub.add_parser("skills"); skl.add_argument("--root", default=".")
+    mp = sub.add_parser("mapping")
+    mp.add_argument("action", nargs="?", default="build",
+                    help="a path to map, or: query | path | explain")
+    mp.add_argument("args", nargs="*")
+    mp.add_argument("--root", default="."); mp.add_argument("--k", type=int, default=8)
+    uip = sub.add_parser("ui"); uip.add_argument("path", nargs="?")
+    uip.add_argument("--root", default="."); uip.add_argument("--port", type=int, default=8799)
+    fd = sub.add_parser("feed"); fd.add_argument("target", nargs="?")
+    fd.add_argument("--domain", default="knowledge"); fd.add_argument("--text")
+    fd.add_argument("--crawl", action="store_true"); fd.add_argument("--depth", type=int, default=1)
+    fd.add_argument("--max", type=int, default=20); fd.add_argument("--root", default=".")
+    ho = sub.add_parser("handoff"); ho.add_argument("--root", default="."); ho.add_argument("-o", "--out")
+    ho.add_argument("--as-claude", action="store_true"); ho.add_argument("--as-agents", action="store_true")
+
+    a = p.parse_args(argv)
+
+    if a.cmd == "mapping":
+        from . import mapping
+        act, rest = a.action, a.args
+        if act == "query":
+            print(json.dumps(mapping.query(a.root, " ".join(rest), k=a.k), indent=2)); return 0
+        if act == "path":
+            if len(rest) < 2:
+                print("usage: gns mapping path \"A\" \"B\""); return 1
+            print(json.dumps(mapping.path(a.root, rest[0], rest[1]), indent=2)); return 0
+        if act == "explain":
+            print(json.dumps(mapping.explain(a.root, " ".join(rest)), indent=2)); return 0
+        target = a.root if act == "build" else act        # `gns mapping .` or `gns mapping ../x`
+        print(json.dumps(mapping.build_map(target), indent=2)); return 0
+    if a.cmd == "ui":
+        from .ui import serve
+        serve(brain_path=a.path, root=a.root, port=a.port); return 0
+    if a.cmd == "feed":
+        from .feed import feed
+        print(json.dumps(feed(a.target, domain=a.domain, text=a.text, crawl=a.crawl,
+                              depth=a.depth, max_pages=a.max, root=a.root), indent=2)); return 0
+    if a.cmd == "handoff":
+        from .handoff import handoff
+        r = handoff(a.root, out=a.out, as_claude=a.as_claude, as_agents=a.as_agents)
+        print(r["markdown"] if "markdown" in r else json.dumps(r, indent=2)); return 0
+
+    if a.cmd == "note":
+        from .agent import AgentMemory
+        print(json.dumps(AgentMemory(root=a.root).remember(a.text, kind=a.kind, subject=a.subject))); return 0
+    if a.cmd == "ask":
+        from .agent import AgentMemory
+        hits = AgentMemory(root=a.root).recall(a.query, kind=a.kind, k=a.k)
+        print(json.dumps(hits, indent=2) if hits else "no relevant memory yet"); return 0
+    if a.cmd == "brief":
+        from .agent import AgentMemory
+        print(AgentMemory(root=a.root).briefing()); return 0
+    if a.cmd == "mem":
+        from .agent import AgentMemory
+        print(json.dumps(AgentMemory(root=a.root).stats(), indent=2)); return 0
+    if a.cmd == "observe":
+        from .agent import AgentMemory
+        print(json.dumps(AgentMemory(root=a.root).observe(a.text))); return 0
+    if a.cmd == "experience":
+        from .agent import AgentMemory
+        print(json.dumps(AgentMemory(root=a.root).experience(a.action, outcome=a.outcome))); return 0
+    if a.cmd == "skill":
+        from .agent import AgentMemory
+        print(json.dumps(AgentMemory(root=a.root).add_skill(a.name, a.when, a.how))); return 0
+    if a.cmd == "skills":
+        from .agent import AgentMemory
+        print(json.dumps(AgentMemory(root=a.root).skills(), indent=2)); return 0
+    if a.cmd == "mcp":
+        from .mcp_server import serve
+        serve(a.root); return 0
+
+    if a.cmd == "inspect":
+        from .artifact import inspect
+        print(json.dumps(inspect(a.path), indent=2)); return 0
+
+    bx = _load_or_new(a.path)
+
+    if a.cmd == "new":
+        bx.export(a.path); print(f"created {a.path}"); return 0
+    if a.cmd == "stats":
+        print(json.dumps(bx.stats(), indent=2)); return 0
+    if a.cmd == "learn":
+        bx.learn(a.domain, a.text, label=a.label, value=a.value)
+        bx.export(a.path); print(f"learned into '{a.domain}' -> {a.path}"); return 0
+    if a.cmd == "train":
+        out = bx.train(a.domain); bx.export(a.path)
+        print(json.dumps(out, indent=2)); return 0
+    if a.cmd == "predict":
+        print(json.dumps(bx.predict(a.domain, a.text), indent=2)); return 0
+    if a.cmd == "recall":
+        print(json.dumps(bx.recall(a.domain, a.text), indent=2)); return 0
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gnosion/core.py

@@ -0,0 +1,223 @@
+"""Gnosion — one portable, self-improving brain with pluggable cognition domains.
+
+    from gnosion import Gnosion
+    bx = Gnosion()                                   # 5 default cognition domains
+    bx.learn("vision", image_bytes, label="plumbing")
+    bx.learn("text",  "how do I reset my password", label="account")
+    bx.remember("design", "auth pattern", "Use JWT in an httpOnly cookie; refresh rotates.")
+    bx.train("vision")                              # refit (champion/challenger)
+    bx.predict("vision", other_image_bytes)         # -> {label, confidence}
+    bx.recall("design", "how should we do auth")    # -> {value, similarity}
+    bx.export("company.gnosion")                     # one portable file
+    bx2 = Gnosion.load("company.gnosion")             # import anywhere
+
+Default domains (the "5 cognitive units"):
+    vision   (classifier, image)   — what kind of thing is in the picture
+    text     (classifier, text)    — intent / category of a message
+    design   (memory,     text)    — system-design & structure conventions (recall)
+    tabular  (classifier, vector)  — outcomes from numeric features
+    memory   (memory,     text)    — general knowledge recall (learns from 1 example)
+Add your own with add_domain().
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .embed import DEFAULT_DIM, make_embedder
+from .heads import HEAD_TYPES, ClassifierHead, MemoryHead
+
+__all__ = ["Gnosion"]
+
+DEFAULT_DOMAINS = [
+    {"name": "vision", "head": "classifier", "modality": "image"},
+    {"name": "text", "head": "classifier", "modality": "text"},
+    {"name": "design", "head": "memory", "modality": "text"},
+    {"name": "tabular", "head": "classifier", "modality": "vector"},
+    {"name": "memory", "head": "memory", "modality": "text"},
+]
+
+
+class _Domain:
+    def __init__(self, name, head, modality, embedder):
+        self.name = name
+        self.head = head
+        self.modality = modality
+        self.embedder = embedder
+
+
+class Gnosion:
+    VERSION = "0.1.0"   # .gnosion on-disk FORMAT version (bump only when the file layout
+    #                     changes) — NOT the package version (see gnosion.__version__)
+
+    def __init__(self, dim: int = DEFAULT_DIM, prefer_fastembed=None,
+                 domains: Optional[List[dict]] = None):
+        # prefer_fastembed: None = auto (use fastembed if installed), True/False = force.
+        self.dim = dim
+        self.prefer_fastembed = prefer_fastembed
+        self.domains: Dict[str, _Domain] = {}
+        for d in (DEFAULT_DOMAINS if domains is None else domains):
+            self.add_domain(d["name"], d.get("head", "classifier"), d.get("modality", "text"))
+
+    # ---------------------------------------------------------------- domains
+    def add_domain(self, name: str, head: str = "classifier", modality: str = "text",
+                   prefer_fastembed="__inherit__") -> None:
+        if head not in HEAD_TYPES:
+            raise ValueError(f"head must be one of {list(HEAD_TYPES)}")
+        pf = self.prefer_fastembed if prefer_fastembed == "__inherit__" else prefer_fastembed
+        emb = make_embedder(modality, self.dim, pf)
+        self.domains[name] = _Domain(name, HEAD_TYPES[head](), modality, emb)
+
+    def _dom(self, name: str) -> _Domain:
+        d = self.domains.get(name)
+        if d is None:
+            raise KeyError(f"unknown domain '{name}' (have {list(self.domains)})")
+        return d
+
+    def _embed(self, name: str, x) -> List[float]:
+        return self._dom(name).embedder.embed(x)
+
+    # ---------------------------------------------------------------- learning
+    def learn(self, domain: str, x, label: Optional[str] = None,
+              value: Optional[str] = None, key: Optional[str] = None,
+              meta: Optional[dict] = None) -> None:
+        """Teach the brain. classifier domains need `label`; memory domains store
+        `value` (or `label`) keyed by the input, with optional `meta`. Gets smarter
+        on every call."""
+        d = self._dom(domain)
+        vec = d.embedder.embed(x)
+        if isinstance(d.head, ClassifierHead):
+            if label is None:
+                raise ValueError(f"domain '{domain}' is a classifier — pass label=")
+            d.head.learn(vec, label, key=key or (str(x)[:60] if not isinstance(x, (bytes, bytearray)) else None))
+        else:  # MemoryHead
+            val = value if value is not None else label
+            if val is None:
+                raise ValueError(f"domain '{domain}' is a memory — pass value=")
+            d.head.learn(vec, val, key=key or str(x)[:200], meta=meta)
+
+    def remember(self, domain: str, cue, value: str, key: Optional[str] = None,
+                 meta: Optional[dict] = None) -> None:
+        """Ergonomic alias for teaching a memory domain: remember(cue -> value)."""
+        self.learn(domain, cue, value=value, key=key, meta=meta)
+
+    def absorb(self, domain: str, question: str, answer: str) -> None:
+        """Learn a Q->A into a memory domain (skips empty/short answers)."""
+        if answer and len(answer.strip()) >= 2:
+            self.learn(domain, question, value=answer)
+
+    def train(self, domain: Optional[str] = None) -> dict:
+        """Refit classifier domain(s). No-op for memory domains. Returns metrics."""
+        out = {}
+        names = [domain] if domain else list(self.domains)
+        for n in names:
+            h = self._dom(n).head
+            if isinstance(h, ClassifierHead):
+                out[n] = h.train()
+        return out
+
+    # ---------------------------------------------------------------- inference
+    def predict(self, domain: str, x) -> dict:
+        d = self._dom(domain)
+        if not isinstance(d.head, ClassifierHead):
+            raise ValueError(f"domain '{domain}' is a memory — use recall()")
+        return d.head.predict(d.embedder.embed(x))
+
+    def recall(self, domain: str, query, min_sim: Optional[float] = None) -> Optional[dict]:
+        d = self._dom(domain)
+        if not isinstance(d.head, MemoryHead):
+            raise ValueError(f"domain '{domain}' is a classifier — use predict()")
+        return d.head.recall(d.embedder.embed(query), min_sim=min_sim)
+
+    def search(self, domain: str, query, k: int = 5, min_sim: float = 0.0) -> List[dict]:
+        """Top-k nearest memory entries in a memory domain."""
+        d = self._dom(domain)
+        if not isinstance(d.head, MemoryHead):
+            raise ValueError(f"domain '{domain}' is a classifier — use predict()")
+        return d.head.search(d.embedder.embed(query), k=k, min_sim=min_sim)
+
+    # ---------------------------------------------------------------- graph
+    def graph(self, k: int = 6, min_sim: float = 0.33, max_nodes_per_domain: int = 300,
+              exclude=()) -> dict:
+        """The brain as a graph: nodes = neurons (memory entries / classifier samples),
+        edges = cosine similarity (top-k >= min_sim) WITHIN each domain. Feeds the UI.
+        `exclude` = domain names to skip (e.g. the mirror 'all' domain, or 'structure'
+        which has its own project view)."""
+        from .linalg import cosine
+        nodes: List[dict] = []
+        blocks = []                              # (start_index, [vecs])
+        for name, d in self.domains.items():
+            if name in exclude:
+                continue
+            if isinstance(d.head, MemoryHead):
+                items = [((e.get("value") or e.get("key") or "")[:80],
+                          int((e.get("meta") or {}).get("hits", 0)),
+                          (e.get("meta") or {}), e["vec"]) for e in d.head.entries]
+            else:
+                items = [(str(s.get("label") or "")[:80], 0, {}, s["vec"]) for s in d.head.samples]
+            start = len(nodes)
+            for label, hits, meta, _v in items:
+                node = {"id": len(nodes), "domain": name, "label": label, "hits": hits}
+                if meta.get("path"):
+                    node["path"] = meta["path"]
+                nodes.append(node)
+            blocks.append((start, [v for _l, _h, _m, v in items] if len(items) <= max_nodes_per_domain else []))
+        edges, seen = [], set()
+        for start, vecs in blocks:
+            n = len(vecs)
+            for a in range(n):
+                sims = sorted(((cosine(vecs[a], vecs[b]), b) for b in range(n) if b != a),
+                              reverse=True)
+                for s, b in sims[:k]:
+                    if s < min_sim:
+                        break
+                    lo, hi = sorted((start + a, start + b))
+                    if (lo, hi) not in seen:
+                        seen.add((lo, hi)); edges.append({"source": lo, "target": hi, "sim": round(s, 3)})
+        return {"nodes": nodes, "edges": edges,
+                "domains": [{"name": n, "count": sum(1 for x in nodes if x["domain"] == n)}
+                            for n in self.domains]}
+
+    # ---------------------------------------------------------------- introspection
+    def stats(self) -> dict:
+        out = {"version": self.VERSION, "dim": self.dim, "domains": {}}
+        for n, d in self.domains.items():
+            if isinstance(d.head, ClassifierHead):
+                out["domains"][n] = {"type": "classifier", "modality": d.modality,
+                                     "samples": len(d.head.samples), "metrics": d.head.metrics}
+            else:
+                out["domains"][n] = {"type": "memory", "modality": d.modality,
+                                     "entries": len(d.head.entries)}
+        return out
+
+    # ---------------------------------------------------------------- (de)serialize
+    def to_dict(self) -> dict:
+        return {
+            "gnosion_version": self.VERSION, "dim": self.dim,
+            "prefer_fastembed": self.prefer_fastembed,
+            "domains": [{"name": n, "modality": d.modality,
+                         "head": d.head.kind, "embedder": d.embedder.kind,
+                         "state": d.head.to_dict()} for n, d in self.domains.items()],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Gnosion":
+        bx = cls(dim=data.get("dim", DEFAULT_DIM),
+                 prefer_fastembed=data.get("prefer_fastembed", False), domains=[])
+        for d in data.get("domains", []):
+            # rebuild the SAME embedder family the brain was built with, so a
+            # fastembed-trained brain reloads with fastembed (dims stay consistent)
+            pf = str(d.get("embedder", "")).startswith("fastembed")
+            bx.add_domain(d["name"], d.get("head", "classifier"), d.get("modality", "text"),
+                          prefer_fastembed=pf)
+            bx.domains[d["name"]].head = HEAD_TYPES[d.get("head", "classifier")].from_dict(d["state"])
+        return bx
+
+    # ---------------------------------------------------------------- portability
+    def export(self, path: str) -> str:
+        from .artifact import export_brain
+        return export_brain(self, path)
+
+    @classmethod
+    def load(cls, path: str) -> "Gnosion":
+        from .artifact import load_brain
+        return load_brain(path)