memfmt 0.1.0__py3-none-any.whl

memfmt/__init__.py

@@ -0,0 +1,32 @@
+"""memfmt — an agent's memory as Markdown files you own.
+
+    from memfmt import load, serialise, write_dir
+
+    memory = load("./memory")
+    memory.procedures[0].reliability      # '92% reliable'
+    write_dir(serialise(memory), "./memory")
+
+Three kinds of memory: entities (what is true), episodes (what happened),
+procedures (how to do something, with the record of it working). Plain
+Markdown, `[[wikilinks]]` for relations, so Obsidian draws the graph with no
+configuration and git gives you diffs, review and rollback for free.
+"""
+
+from .model import (Entity, Episode, Knowledge, Memory, Procedure, Relation,
+                    Revision, Step, canonical)
+from .parse import (MemfmtError, file_type, load, parse, parse_frontmatter,
+                    read_dir, write_dir)
+from .serialize import INDEX, ROOT, TYPE_KEY, serialise, slugify
+
+__version__ = "0.1.0"
+
+#: American spelling, same function — the CLI and half the world write it this way.
+serialize = serialise
+
+__all__ = [
+    "Entity", "Episode", "Knowledge", "Memory", "Procedure", "Relation",
+    "Revision", "Step", "canonical",
+    "load", "parse", "parse_frontmatter", "read_dir", "write_dir", "file_type",
+    "serialise", "serialize", "slugify",
+    "MemfmtError", "TYPE_KEY", "ROOT", "INDEX", "__version__",
+]

memfmt/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

memfmt/cli.py

@@ -0,0 +1,166 @@
+"""`memfmt` — read, check and pull from a memory folder.
+
+Everything here works on files alone: no account, no server, no network. That
+is the point. A tool that needs a login to be useful is a landing page.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from . import __version__
+from .model import Memory
+from .parse import MemfmtError, file_type, parse, parse_frontmatter, read_dir
+from .serialize import INDEX, serialise
+
+_WORD = re.compile(r"[a-z0-9]+")
+
+
+def _words(text: str) -> set[str]:
+    return set(_WORD.findall((text or "").lower()))
+
+
+def _counts(memory: Memory) -> str:
+    return (f"{len(memory.entities)} entities, "
+            f"{len(memory.episodes)} episodes, "
+            f"{len(memory.procedures)} procedures")
+
+
+def cmd_stat(args) -> int:
+    memory = parse(read_dir(args.path))
+    print(_counts(memory))
+    tested = [p for p in memory.procedures if p.success_count + p.fail_count]
+    if tested:
+        print("\nprocedures with a track record:")
+        for p in sorted(tested, key=lambda p: -(p.success_count + p.fail_count)):
+            print(f"  {p.name}  v{p.version}  "
+                  f"{p.success_count}✓/{p.fail_count}✗  {p.reliability}")
+    untested = len(memory.procedures) - len(tested)
+    if untested:
+        print(f"\n{untested} untested — no evidence either way yet.")
+    return 0
+
+
+def cmd_validate(args) -> int:
+    """Read every file, then write it back in memory and compare.
+
+    Anything that does not survive that is a place where a tool would lose a
+    piece of somebody's memory, so it is reported as a file, not a warning.
+    """
+    tree = read_dir(args.path)
+    typed = {}
+    for path, text in tree.items():
+        fields, _ = parse_frontmatter(text)
+        if file_type(fields):
+            typed[path] = text
+
+    if not typed:
+        print(f"no memfmt files under {args.path}", file=sys.stderr)
+        return 1
+
+    memory = parse(typed)
+    root = next((p.split("/", 1)[0] for p in typed if "/" in p), "memory")
+    again = serialise(memory, root=root)
+
+    lossy = []
+    for path, text in sorted(typed.items()):
+        if path.endswith(INDEX):
+            continue          # regenerated, not authored
+        rewritten = again.get(path)
+        if rewritten is None:
+            lossy.append((path, "not reproduced"))
+        elif rewritten.strip() != text.strip():
+            lossy.append((path, "changes when rewritten"))
+
+    print(f"{len(typed)} files, {_counts(memory)}")
+    if lossy:
+        print(f"\n{len(lossy)} would not survive a round trip:")
+        for path, why in lossy:
+            print(f"  {path} — {why}")
+        return 1
+    print("valid — every file survives a round trip unchanged")
+    return 0
+
+
+def cmd_context(args) -> int:
+    """Print the memory most relevant to a question, ready to paste or pipe.
+
+    Relevance here is word overlap, which is honest about what files alone can
+    do. It is also where this stops being enough: past a few hundred files you
+    want embeddings, and that needs a server.
+    """
+    query = _words(" ".join(args.query))
+    if not query:
+        print("nothing to look for", file=sys.stderr)
+        return 1
+
+    scored = []
+    for path, text in read_dir(args.path).items():
+        fields, body = parse_frontmatter(text)
+        if not file_type(fields) or path.endswith(INDEX):
+            continue
+        words = _words(body)
+        overlap = query & words
+        if overlap:
+            # How many of the asked-about things a file mentions comes first;
+            # density only breaks ties. Ranking by density alone let a stub
+            # entity whose only word was "Railway" outrank the procedure that
+            # actually answered the question.
+            scored.append(((len(overlap), 1 / (1 + len(words))), path, body))
+
+    if not scored:
+        print("nothing relevant", file=sys.stderr)
+        return 1
+
+    budget = args.chars
+    used = 0
+    for _, path, body in sorted(scored, reverse=True)[:args.limit]:
+        chunk = body.strip()
+        if used + len(chunk) > budget:
+            break
+        print(f"<!-- {path} -->")
+        print(chunk)
+        print()
+        used += len(chunk)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="memfmt",
+        description="An agent's memory as Markdown files you own.")
+    parser.add_argument("--version", action="version", version=f"memfmt {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("stat", help="what is in a memory folder")
+    p.add_argument("path", nargs="?", default="memory", type=Path)
+    p.set_defaults(func=cmd_stat)
+
+    p = sub.add_parser("validate", help="check every file survives a round trip")
+    p.add_argument("path", nargs="?", default="memory", type=Path)
+    p.set_defaults(func=cmd_validate)
+
+    p = sub.add_parser("context", help="print the memory relevant to a question")
+    p.add_argument("path", type=Path)
+    p.add_argument("query", nargs="+")
+    p.add_argument("--limit", type=int, default=8, help="most files to print")
+    p.add_argument("--chars", type=int, default=8000, help="rough size budget")
+    p.set_defaults(func=cmd_context)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except MemfmtError as err:
+        print(str(err), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

memfmt/model.py

@@ -0,0 +1,141 @@
+"""The shape of an agent's memory.
+
+Three kinds, because agents forget in three different ways: what is true
+(entities and their facts), what happened (episodes), and how to do something
+(procedures, with the track record that says whether to trust them).
+
+These are plain dataclasses on purpose. The format is files; this module is
+only the in-memory view of them, so that `parse(serialise(m)) == m` is a
+statement you can test rather than hope for.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Relation:
+    """An edge between two entities. `target` is the other entity's name, not an
+    id: names are what a human reads in a link, and the format is meant to stay
+    legible after the database that produced it is gone."""
+
+    type: str
+    target: str
+    direction: str = "outgoing"
+    detail: str | None = None
+
+
+@dataclass
+class Knowledge:
+    """A longer note attached to an entity — a snippet, a config, a quote."""
+
+    type: str = "note"
+    title: str = ""
+    content: str = ""
+    artifact: str | None = None
+
+
+@dataclass
+class Entity:
+    name: str
+    entity_type: str | None = None
+    id: str | None = None
+    facts: list[str] = field(default_factory=list)
+    relations: list[Relation] = field(default_factory=list)
+    knowledge: list[Knowledge] = field(default_factory=list)
+    #: Frontmatter this library does not know about, kept verbatim so a
+    #: hand-written field survives being read and written back.
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass
+class Episode:
+    """Something that happened, and how it turned out.
+
+    `outcome` is what makes an episode worth keeping: an event with no result
+    teaches nothing.
+    """
+
+    summary: str
+    id: str | None = None
+    happened: str | None = None
+    outcome: str | None = None
+    valence: str | None = None
+    importance: int | None = None
+    participants: list[str] = field(default_factory=list)
+    context: str | None = None
+    #: Frontmatter this library does not know about, kept verbatim so a
+    #: hand-written field survives being read and written back.
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass
+class Step:
+    action: str
+    detail: str | None = None
+
+
+@dataclass
+class Revision:
+    """One change to a procedure. Kept because the reason a workflow changed is
+    usually more useful than the workflow itself."""
+
+    version_before: int
+    version_after: int
+    reason: str = ""
+    date: str | None = None
+
+
+@dataclass
+class Procedure:
+    """A workflow the agent learned, with the record of it working or not.
+
+    `success_count`/`fail_count` are the point. A procedure without a track
+    record is a guess written down; with one, it is evidence.
+    """
+
+    name: str
+    id: str | None = None
+    version: int = 1
+    success_count: int = 0
+    fail_count: int = 0
+    trigger: str | None = None
+    preconditions: list[str] = field(default_factory=list)
+    steps: list[Step] = field(default_factory=list)
+    evolution: list[Revision] = field(default_factory=list)
+    #: Frontmatter this library does not know about, kept verbatim so a
+    #: hand-written field survives being read and written back.
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def reliability(self) -> str:
+        total = self.success_count + self.fail_count
+        if total == 0:
+            return "untested"
+        return f"{round(100 * self.success_count / total)}% reliable"
+
+
+@dataclass
+class Memory:
+    entities: list[Entity] = field(default_factory=list)
+    episodes: list[Episode] = field(default_factory=list)
+    procedures: list[Procedure] = field(default_factory=list)
+    profile: str | None = None
+
+
+def canonical(memory: Memory) -> Memory:
+    """The same memory in a stable order.
+
+    A memory folder is a set of files, so reading one back cannot preserve the
+    order of the list that produced it. Two memories are equal when they hold
+    the same things, and this is how you ask that question — it is also what
+    keeps a git diff to the lines that actually changed.
+    """
+    return Memory(
+        entities=sorted(memory.entities, key=lambda e: (e.name, e.id or "")),
+        episodes=sorted(memory.episodes,
+                        key=lambda e: (e.happened or "", e.summary, e.id or "")),
+        procedures=sorted(memory.procedures, key=lambda p: (p.name, p.id or "")),
+        profile=memory.profile,
+    )

memfmt/parse.py

@@ -0,0 +1,337 @@
+"""Files in, memory out — the half that makes this a format rather than a doc.
+
+A serialiser alone gives you an export. A parser is what lets someone else's
+tool read what your tool wrote, edit it by hand, keep it in git, and hand it
+back. Everything here exists so that `parse(serialise(m)) == m`.
+
+The YAML reader is deliberately a small hand-rolled subset instead of PyYAML:
+this library writes the frontmatter it reads, the subset is `key: scalar` and
+`key:` followed by `  - item`, and a format that drags in a parser dependency
+is a format people think twice about adopting.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .model import Entity, Episode, Knowledge, Memory, Procedure, Relation, Revision, Step
+from .serialize import DASH, INDEX, LEGACY_TYPE_KEY, TYPE_KEY
+
+#: Frontmatter fields the model holds as integers. Everything else stays text —
+#: guessing types from shape would turn a version string like "2019" into a
+#: number and quietly change what the file said.
+_INT_FIELDS = {"importance", "version", "success_count", "fail_count"}
+
+#: Frontmatter each kind of file is responsible for. Everything else is
+#: somebody's own field and is handed back untouched on the way out.
+_KNOWN = {
+    "entity": {TYPE_KEY, LEGACY_TYPE_KEY, "entity_type", "id"},
+    "episode": {TYPE_KEY, LEGACY_TYPE_KEY, "id", "happened", "outcome",
+                "valence", "importance", "participants"},
+    "procedure": {TYPE_KEY, LEGACY_TYPE_KEY, "id", "version",
+                  "success_count", "fail_count"},
+}
+
+_FM = re.compile(r"\A---\n(.*?)\n---\n?", re.S)
+_H1 = re.compile(r"^# (.*)$", re.M)
+_RELIABILITY = re.compile(r"\s*\(v\d+ · [^)]*\)\s*$")
+_RELATION = re.compile(
+    r"^- (?P<verb>.*?) (?P<arrow>→|←) \[\[(?P<link>[^\]]+)\]\](?P<rest>.*)$")
+_KNOWLEDGE = re.compile(r"^\*\*\[(?P<kind>[^\]]*)\] (?P<title>.*?)\*\*(?P<rest>.*)$")
+_STEP = re.compile(r"^\d+\. (?P<text>.*)$")
+_REVISION = re.compile(
+    r"^- v(?P<before>\d+) → v(?P<after>\d+)(?: \((?P<date>[^)]*)\))?: (?P<reason>.*)$")
+
+
+class MemfmtError(ValueError):
+    """A file claims to be memfmt but cannot be read as it."""
+
+
+def _unquote(text: str) -> str:
+    text = text.strip()
+    if len(text) >= 2 and text[0] == '"' and text[-1] == '"':
+        return text[1:-1].replace('\\"', '"').replace("\\\\", "\\")
+    return text
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Split a file into its frontmatter mapping and the body below it."""
+    match = _FM.match(text)
+    if not match:
+        return {}, text
+
+    fields: dict = {}
+    key: str | None = None
+    for raw in match.group(1).split("\n"):
+        if raw.startswith("  - ") and key is not None:
+            fields.setdefault(key, [])
+            if not isinstance(fields[key], list):
+                fields[key] = []
+            fields[key].append(_unquote(raw[4:]))
+            continue
+        if ":" not in raw:
+            continue
+        key, _, value = raw.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if value == "":
+            fields[key] = []          # a list header; items follow
+            continue
+        value = _unquote(value)
+        if key in _INT_FIELDS:
+            try:
+                value = int(value)
+            except ValueError:
+                pass
+        fields[key] = value
+
+    return fields, text[match.end():]
+
+
+def file_type(fields: dict) -> str | None:
+    return fields.get(TYPE_KEY) or fields.get(LEGACY_TYPE_KEY)
+
+
+def _extra(fields: dict, kind: str) -> dict:
+    """Frontmatter this library has no opinion about.
+
+    Dropping it would mean a file someone hand-edited comes back smaller than
+    they left it, which is the one thing a memory format must never do.
+    """
+    known = _KNOWN[kind]
+    return {k: v for k, v in fields.items() if k not in known}
+
+
+def _title(body: str) -> str:
+    match = _H1.search(body)
+    return match.group(1).strip() if match else ""
+
+
+def _sections(body: str) -> dict[str, list[str]]:
+    """Body split by `## ` headings. Everything before the first one lands under
+    the empty key, which is where an episode's context and a procedure's
+    `**When**` line live."""
+    out: dict[str, list[str]] = {"": []}
+    current = ""
+    for line in body.split("\n"):
+        if line.startswith("## "):
+            current = line[3:].strip()
+            out.setdefault(current, [])
+            continue
+        out[current].append(line)
+    return out
+
+
+def _bullets(lines: list[str]) -> list[str]:
+    return [ln[2:].strip() for ln in lines if ln.startswith("- ")]
+
+
+def parse_entity(fields: dict, body: str) -> Entity:
+    sections = _sections(body)
+    entity = Entity(
+        name=_title(body),
+        entity_type=fields.get("entity_type") or None,
+        id=fields.get("id") or None,
+        facts=_bullets(sections.get("Facts", [])),
+        extra=_extra(fields, "entity"),
+    )
+
+    for line in sections.get("Relations", []):
+        match = _RELATION.match(line)
+        if not match:
+            continue
+        link = match.group("link")
+        # `[[stem|Original name]]` — the alias is the real name; the stem is
+        # only what the filename had to become.
+        target = link.split("|", 1)[1] if "|" in link else link
+        rest = match.group("rest")
+        detail = rest[len(DASH):].strip() if rest.startswith(DASH) else None
+        entity.relations.append(Relation(
+            type=match.group("verb").strip(),
+            target=target.strip(),
+            direction="incoming" if match.group("arrow") == "←" else "outgoing",
+            detail=detail or None,
+        ))
+
+    lines = sections.get("Knowledge", [])
+    i = 0
+    while i < len(lines):
+        match = _KNOWLEDGE.match(lines[i])
+        i += 1
+        if not match:
+            continue
+        rest = match.group("rest")
+        content = rest[len(DASH):].strip() if rest.startswith(DASH) else ""
+        artifact = None
+        # An optional fenced block belongs to the entry above it.
+        j = i
+        while j < len(lines) and lines[j].strip() == "":
+            j += 1
+        if j < len(lines) and lines[j].strip() == "```":
+            end = j + 1
+            while end < len(lines) and lines[end].strip() != "```":
+                end += 1
+            artifact = "\n".join(lines[j + 1:end])
+            i = end + 1
+        entity.knowledge.append(Knowledge(
+            type=match.group("kind") or "note",
+            title=match.group("title").strip(),
+            content=content,
+            artifact=artifact,
+        ))
+
+    return entity
+
+
+def parse_episode(fields: dict, body: str) -> Episode:
+    lines = _sections(body).get("", [])
+    context: list[str] = []
+    seen_title = False
+    for line in lines:
+        if line.startswith("# "):
+            seen_title = True
+            continue
+        # The `**Outcome**` line is a rendering of the frontmatter field, not a
+        # second source of truth — skip it rather than fold it into context.
+        if line.startswith("**Outcome**"):
+            continue
+        if seen_title:
+            context.append(line)
+
+    participants = fields.get("participants")
+    return Episode(
+        summary=_title(body),
+        id=fields.get("id") or None,
+        happened=fields.get("happened") or None,
+        outcome=fields.get("outcome") or None,
+        valence=fields.get("valence") or None,
+        importance=fields.get("importance") if isinstance(fields.get("importance"), int) else None,
+        participants=participants if isinstance(participants, list) else [],
+        context="\n".join(context).strip() or None,
+        extra=_extra(fields, "episode"),
+    )
+
+
+def parse_procedure(fields: dict, body: str) -> Procedure:
+    sections = _sections(body)
+    head = sections.get("", [])
+
+    trigger = None
+    preconditions: list[str] = []
+    in_pre = False
+    for line in head:
+        if line.startswith("**When**"):
+            rest = line[len("**When**"):]
+            trigger = rest[len(DASH):].strip() if rest.startswith(DASH) else rest.strip()
+            continue
+        if line.startswith("**Preconditions**"):
+            in_pre = True
+            continue
+        if in_pre:
+            if line.startswith("- "):
+                preconditions.append(line[2:].strip())
+            elif line.strip():
+                in_pre = False
+
+    steps = []
+    for line in sections.get("Steps", []):
+        match = _STEP.match(line)
+        if not match:
+            continue
+        text = match.group("text")
+        action, sep, detail = text.partition(DASH)
+        steps.append(Step(action=action.strip(), detail=detail.strip() if sep else None))
+
+    evolution = []
+    for line in sections.get("Evolution", []):
+        match = _REVISION.match(line)
+        if not match:
+            continue
+        evolution.append(Revision(
+            version_before=int(match.group("before")),
+            version_after=int(match.group("after")),
+            reason=match.group("reason").strip(),
+            date=match.group("date") or None,
+        ))
+
+    version = fields.get("version")
+    return Procedure(
+        # The `(v3 · 92% reliable)` suffix is derived from the frontmatter for
+        # the reader's benefit; the frontmatter stays the source of truth.
+        name=_RELIABILITY.sub("", _title(body)).strip(),
+        id=fields.get("id") or None,
+        version=version if isinstance(version, int) else 1,
+        success_count=fields.get("success_count") if isinstance(fields.get("success_count"), int) else 0,
+        fail_count=fields.get("fail_count") if isinstance(fields.get("fail_count"), int) else 0,
+        trigger=trigger or None,
+        preconditions=preconditions,
+        steps=steps,
+        evolution=evolution,
+        extra=_extra(fields, "procedure"),
+    )
+
+
+def parse(tree: dict[str, str]) -> Memory:
+    """A `{path: text}` tree back into a Memory.
+
+    Files that carry no type marker are skipped rather than guessed at: a
+    memory folder living inside somebody's vault will sit next to notes that
+    are none of our business.
+    """
+    memory = Memory()
+    for path in sorted(tree):
+        if not path.endswith(".md"):
+            continue
+        fields, body = parse_frontmatter(tree[path])
+        kind = file_type(fields)
+        if kind == "entity":
+            memory.entities.append(parse_entity(fields, body))
+        elif kind == "episode":
+            memory.episodes.append(parse_episode(fields, body))
+        elif kind == "procedure":
+            memory.procedures.append(parse_procedure(fields, body))
+        elif kind == "profile":
+            text = body.split("# Profile", 1)[-1].strip()
+            memory.profile = text or None
+    return memory
+
+
+# ---- directories ----------------------------------------------------------
+
+def read_dir(root: str | Path) -> dict[str, str]:
+    """Every Markdown file under `root`, keyed by its path relative to it."""
+    root = Path(root)
+    if not root.is_dir():
+        raise MemfmtError(f"not a directory: {root}")
+    return {
+        str(p.relative_to(root)): p.read_text(encoding="utf-8")
+        for p in sorted(root.rglob("*.md"))
+    }
+
+
+def write_dir(tree: dict[str, str], root: str | Path) -> list[str]:
+    """Write a tree under `root`, creating parents. Returns the paths written."""
+    root = Path(root)
+    written = []
+    for rel, text in sorted(tree.items()):
+        target = root / rel
+        # A path from a tree should never climb out of the root it is given.
+        if not str(target.resolve()).startswith(str(root.resolve())):
+            raise MemfmtError(f"path escapes the root: {rel}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8")
+        written.append(str(target))
+    return written
+
+
+def load(root: str | Path) -> Memory:
+    """Read a memory directory straight into a Memory."""
+    return parse(read_dir(root))
+
+
+__all__ = [
+    "parse", "parse_frontmatter", "parse_entity", "parse_episode",
+    "parse_procedure", "file_type", "read_dir", "write_dir", "load",
+    "MemfmtError", "INDEX",
+]

memfmt/serialize.py

@@ -0,0 +1,302 @@
+"""Memory in, `{path: text}` out.
+
+Nothing is written here. The caller decides whether that becomes a directory,
+a zip, or files in an Obsidian vault — which is why the same serialiser can
+back a CLI, an HTTP endpoint and an editor plugin without the three drifting.
+
+The output is deliberately boring Markdown: headings, bullets, `[[wikilinks]]`.
+A person with no tooling can read it, and Obsidian draws the graph from it with
+no configuration, because the links *are* the graph.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+
+from .model import Entity, Episode, Knowledge, Memory, Procedure, Relation, Revision
+
+#: Frontmatter key that marks a file as belonging to this format. Namespaced so
+#: it cannot collide with the frontmatter people already keep in their vaults.
+TYPE_KEY = "memfmt_type"
+
+#: Read as an alias when parsing, so trees written by Mengram before the format
+#: was split out still load.
+LEGACY_TYPE_KEY = "mengram_type"
+
+ROOT = "memory"
+INDEX = "MEMORY.md"
+
+#: Separates a value from its note: `works at → [[Acme]] — since 2019`.
+DASH = " — "
+
+_UNSAFE = re.compile(r'[\\/:*?"<>|\x00-\x1f]')
+_SPACES = re.compile(r"\s+")
+MAX_STEM = 80
+
+
+def slugify(name: str) -> str:
+    """A filename that survives every filesystem while still reading as the name.
+
+    Punctuation is preserved wherever it is safe to: these stems are note titles
+    people will see and link by, not URL slugs. The original always goes in the
+    `# H1`, so nothing is lost when a long name has to be trimmed.
+    """
+    stem = _UNSAFE.sub("-", name or "")
+    stem = _SPACES.sub(" ", stem).strip(" .")
+    if len(stem) > MAX_STEM:
+        stem = stem[:MAX_STEM].rstrip(" .-")
+    return stem or "unnamed"
+
+
+def _unique(stem: str, taken: set) -> str:
+    """Two names can collide once unsafe characters are replaced. Numbering the
+    later ones is ugly; silently overwriting someone's memory is worse."""
+    if stem not in taken:
+        taken.add(stem)
+        return stem
+    n = 2
+    while f"{stem} ({n})" in taken:
+        n += 1
+    stem = f"{stem} ({n})"
+    taken.add(stem)
+    return stem
+
+
+def _needs_quotes(text: str) -> bool:
+    if text == "":
+        return True
+    if text[0] in "-?:,[]{}#&*!|>'\"%@`":
+        return True
+    return ":" in text or "\n" in text
+
+
+def _scalar(value) -> str:
+    """One YAML scalar, quoted only when it would otherwise be misread.
+    Unquoted frontmatter is far easier to skim, and skimming is the point."""
+    if value is None:
+        return '""'
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value)
+    if text != text.strip() or _needs_quotes(text):
+        return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return text
+
+
+def frontmatter(fields: dict) -> str:
+    """YAML block. Empty values are dropped rather than written as nulls, so the
+    header stays short enough to read at a glance."""
+    lines = ["---"]
+    for key, value in fields.items():
+        if value is None or value == "" or value == []:
+            continue
+        if isinstance(value, list):
+            lines.append(f"{key}:")
+            lines.extend(f"  - {_scalar(v)}" for v in value)
+        else:
+            lines.append(f"{key}: {_scalar(value)}")
+    lines.append("---")
+    return "\n".join(lines)
+
+
+def _line(text: str) -> str:
+    """Collapse a value onto one line.
+
+    Facts, steps and relation notes are bullets, and a bullet that contains a
+    newline stops being one. Collapsing here keeps what the file says identical
+    to what a parser reads back.
+    """
+    return _SPACES.sub(" ", (text or "").strip())
+
+
+def wikilink(name: str, targets: dict) -> str:
+    """A link Obsidian can follow. When the file had to be renamed to be safe,
+    the link carries an alias so it still reads as the real name."""
+    stem = targets.get(name)
+    if stem is None:
+        # The target is outside this tree. Link anyway: Obsidian renders it as
+        # an unresolved node, which is honest about something being there.
+        stem = slugify(name)
+    return f"[[{stem}]]" if stem == name else f"[[{stem}|{name}]]"
+
+
+# ---- files ----------------------------------------------------------------
+
+def entity_file(entity: Entity, targets: dict) -> str:
+    body = [
+        frontmatter({
+            TYPE_KEY: "entity",
+            "entity_type": entity.entity_type,
+            "id": entity.id,
+            **entity.extra,
+        }),
+        "",
+        f"# {entity.name}",
+    ]
+
+    facts = [_line(f) for f in entity.facts if _line(f)]
+    if facts:
+        body += ["", "## Facts", ""] + [f"- {f}" for f in facts]
+
+    relations = [r for r in entity.relations if r.target]
+    if relations:
+        body += ["", "## Relations", ""]
+        for r in relations:
+            arrow = "←" if r.direction == "incoming" else "→"
+            detail = f"{DASH}{_line(r.detail)}" if r.detail else ""
+            body.append(f"- {_line(r.type) or 'related to'} {arrow} "
+                        f"{wikilink(r.target, targets)}{detail}")
+
+    knowledge = [k for k in entity.knowledge if k.content or k.title]
+    if knowledge:
+        body += ["", "## Knowledge", ""]
+        for k in knowledge:
+            body.append(f"**[{k.type or 'note'}] {_line(k.title)}**"
+                        f"{DASH}{_line(k.content)}".rstrip(" —"))
+            if k.artifact:
+                body += ["", "```", str(k.artifact).rstrip(), "```"]
+
+    return "\n".join(body).rstrip() + "\n"
+
+
+def episode_file(episode: Episode) -> str:
+    body = [
+        frontmatter({
+            TYPE_KEY: "episode",
+            "id": episode.id,
+            "happened": episode.happened,
+            "outcome": episode.outcome,
+            "valence": episode.valence,
+            "importance": episode.importance,
+            "participants": episode.participants,
+            **episode.extra,
+        }),
+        "",
+        f"# {episode.summary or 'untitled'}",
+    ]
+    if episode.context:
+        body += ["", episode.context.strip()]
+    if episode.outcome:
+        body += ["", f"**Outcome**{DASH}{_line(episode.outcome)}"]
+    return "\n".join(body).rstrip() + "\n"
+
+
+def procedure_file(procedure: Procedure) -> str:
+    """The file this format exists for.
+
+    A workflow on its own is a guess someone wrote down. With `11 ✓ / 1 ✗` and
+    the revisions that produced it, it is evidence — and that is the part no
+    other memory format carries.
+    """
+    body = [
+        frontmatter({
+            TYPE_KEY: "procedure",
+            "id": procedure.id,
+            "version": procedure.version,
+            "success_count": procedure.success_count,
+            "fail_count": procedure.fail_count,
+            **procedure.extra,
+        }),
+        "",
+        f"# {procedure.name} (v{procedure.version} · {procedure.reliability})",
+    ]
+
+    if procedure.trigger:
+        body += ["", f"**When**{DASH}{_line(procedure.trigger)}"]
+
+    preconditions = [_line(p) for p in procedure.preconditions if _line(p)]
+    if preconditions:
+        body += ["", "**Preconditions**", ""] + [f"- {p}" for p in preconditions]
+
+    if procedure.steps:
+        body += ["", "## Steps", ""]
+        for i, step in enumerate(procedure.steps, 1):
+            text = _line(step.action)
+            if step.detail:
+                detail = _line(step.detail)
+                text = f"{text}{DASH}{detail}" if text else detail
+            body.append(f"{i}. {text}")
+
+    if procedure.evolution:
+        body += ["", "## Evolution", ""]
+        for entry in procedure.evolution:
+            stamp = f" ({entry.date})" if entry.date else ""
+            body.append(f"- v{entry.version_before} → v{entry.version_after}"
+                        f"{stamp}: {_line(entry.reason)}")
+
+    return "\n".join(body).rstrip() + "\n"
+
+
+def index_file(memory: Memory, entity_stems: list, generated: str | None = None) -> str:
+    body = [
+        frontmatter({TYPE_KEY: "index",
+                     "generated": generated or date.today().isoformat()}),
+        "",
+        "# Memory",
+        "",
+    ]
+    if not (memory.entities or memory.episodes or memory.procedures):
+        body += [
+            "This memory is empty — nothing has been remembered yet.",
+            "",
+            "Facts, events and the workflows an agent learns will appear here",
+            "as files you own.",
+        ]
+        return "\n".join(body) + "\n"
+
+    body += [
+        f"- {len(memory.entities)} entities",
+        f"- {len(memory.episodes)} episodes",
+        f"- {len(memory.procedures)} procedures",
+    ]
+    if entity_stems:
+        body += ["", "## Entities", ""] + [f"- [[{s}]]" for s in sorted(entity_stems)]
+    return "\n".join(body).rstrip() + "\n"
+
+
+def serialise(memory: Memory, root: str = ROOT,
+              generated: str | None = None) -> dict[str, str]:
+    """The whole memory as `{relative path: file text}`."""
+    prefix = f"{root}/" if root else ""
+
+    # Names resolve to stems before anything is written, so a relation
+    # serialised before its target still links to the right file.
+    taken: set = set()
+    targets = {e.name: _unique(slugify(e.name), taken) for e in memory.entities}
+
+    tree: dict[str, str] = {}
+    for entity in memory.entities:
+        tree[f"{prefix}entities/{targets[entity.name]}.md"] = entity_file(entity, targets)
+
+    ep_taken: set = set()
+    for episode in memory.episodes:
+        base = slugify(episode.summary or "episode")
+        stem = _unique(f"{episode.happened}-{base}" if episode.happened else base, ep_taken)
+        tree[f"{prefix}episodes/{stem}.md"] = episode_file(episode)
+
+    proc_taken: set = set()
+    for procedure in memory.procedures:
+        stem = _unique(slugify(procedure.name), proc_taken)
+        tree[f"{prefix}procedures/{stem}.md"] = procedure_file(procedure)
+
+    if memory.profile:
+        tree[f"{prefix}profile.md"] = "\n".join([
+            frontmatter({TYPE_KEY: "profile",
+                         "generated": generated or date.today().isoformat()}),
+            "", "# Profile", "", memory.profile.strip(),
+        ]) + "\n"
+
+    tree[f"{prefix}{INDEX}"] = index_file(memory, list(targets.values()), generated)
+    return tree
+
+
+# Kept so `from memfmt.serialize import *` reads sensibly in a REPL.
+__all__ = [
+    "serialise", "slugify", "wikilink", "frontmatter",
+    "entity_file", "episode_file", "procedure_file", "index_file",
+    "TYPE_KEY", "LEGACY_TYPE_KEY", "ROOT", "INDEX", "DASH",
+    "Entity", "Episode", "Knowledge", "Memory", "Procedure", "Relation", "Revision",
+]

memfmt-0.1.0.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: memfmt
+Version: 0.1.0
+Summary: An agent's memory as Markdown files you own — read, write and check the format.
+Project-URL: Homepage, https://github.com/alibaizhanov/memfmt
+Project-URL: Source, https://github.com/alibaizhanov/memfmt
+Author: Ali Baizhanov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,format,llm,markdown,memory,obsidian
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# memfmt
+
+**An agent's memory as Markdown files you own.**
+
+Every agent that remembers anything invents its own way to store it: one
+`MEMORY.md` that grows until it stops fitting in context, a bespoke JSON blob,
+a folder of notes with no rules. Nobody can read anybody else's, nothing
+diffs cleanly, and moving between tools means writing a converter.
+
+memfmt is a small spec and a dependency-free Python library for the boring
+version of that: memory as plain Markdown, one thing per file, relations as
+`[[wikilinks]]`. Git gives you diffs, review and rollback. Obsidian draws the
+graph with no configuration, because the links *are* the graph.
+
+```
+memory/
+  MEMORY.md                            index — what is in here
+  entities/Ali.md                      what is true
+  episodes/2026-07-30-deploy-failed.md what happened
+  procedures/deploy to Railway.md      how to do it, and whether it works
+  profile.md
+```
+
+No account, no server, no network. This library reads and writes files.
+
+---
+
+## Install
+
+```bash
+pip install memfmt
+```
+
+## Use it
+
+```bash
+memfmt stat ./memory        # what is in here
+memfmt validate ./memory    # would any file lose data if a tool rewrote it?
+memfmt context ./memory "why did the deploy fail"   # the relevant bits, to pipe into a model
+```
+
+```python
+from memfmt import load, serialise, write_dir, canonical
+
+memory = load("./memory")
+
+for p in memory.procedures:
+    print(p.name, p.version, p.reliability)   # deploy to Railway 3 92% reliable
+
+write_dir(serialise(memory), "./memory")
+```
+
+`memfmt context` is the one to try first. It picks the files relevant to a
+question and prints them, so you can pipe your agent's own memory into a
+prompt without a database:
+
+```bash
+memfmt context ./memory "deploy railway pool" | pbcopy
+```
+
+---
+
+## The format
+
+Three kinds of memory, because agents forget in three different ways.
+
+### Entities — what is true
+
+`memory/entities/<name>.md`
+
+````markdown
+---
+memfmt_type: entity
+entity_type: person
+id: e1
+---
+
+# Ali
+
+## Facts
+
+- prefers Rust for memory safety
+- based in Tokyo
+
+## Relations
+
+- works at → [[Mengram]] — since 2024
+- mentored by ← [[Kenji]]
+
+## Knowledge
+
+**[snippet] deploy command** — how the service ships
+
+```
+railway up --detach
+```
+````
+
+`→` is outgoing, `←` incoming. Text after ` — ` is a note on the relation.
+When a name cannot be a filename, the link carries an alias and the real name
+survives: `[[cloud-api.py|cloud/api.py]]`.
+
+### Episodes — what happened
+
+`memory/episodes/<date>-<summary>.md`
+
+```markdown
+---
+memfmt_type: episode
+id: ep1
+happened: 2026-07-30
+outcome: rolled back, raised pool_max
+valence: negative
+importance: 4
+participants:
+  - Ali
+  - Railway
+---
+
+# deploy failed on a cold pool
+
+Two workers booted at once and the session pooler refused the fourth client.
+
+**Outcome** — rolled back, raised pool_max
+```
+
+An event with no outcome teaches nothing, so `outcome` is the field that earns
+an episode its place.
+
+### Procedures — how to do something, and whether it works
+
+`memory/procedures/<name>.md`
+
+```markdown
+---
+memfmt_type: procedure
+id: p1
+version: 3
+success_count: 11
+fail_count: 1
+---
+
+# deploy to Railway (v3 · 92% reliable)
+
+**When** — a change lands on main
+
+**Preconditions**
+
+- tests pass
+- pool_max is set
+
+## Steps
+
+1. push to main — the webhook does the rest
+2. watch the boot log
+3. verify /health — expect 200 within 60s
+
+## Evolution
+
+- v1 → v2 (2026-06-02): added the health check
+- v2 → v3: wait for the pool before probing
+```
+
+This is the file the format exists for. A workflow on its own is a guess
+somebody wrote down. With `11 ✓ / 1 ✗` and the revisions that produced it, it
+is evidence — and an agent can tell the difference between a step that has
+worked eleven times and one nobody has ever run.
+
+---
+
+## Rules
+
+A short list, because a format nobody can hold in their head gets implemented
+wrong.
+
+1. **Frontmatter is the source of truth.** The `(v3 · 92% reliable)` in a
+   heading is rendered from it for the reader. Edit the heading and the
+   numbers do not change — the parser reads the frontmatter.
+2. **`memfmt_type` marks a file as ours.** Files without it are ignored, so a
+   memory folder can live inside a vault full of somebody's own notes.
+3. **Unknown fields are left alone.** Nothing is silently dropped for being
+   unrecognised.
+4. **Bullets are one line.** Facts, steps and relation notes are collapsed to
+   a single line when written, so what a file says and what a parser reads
+   back are the same thing.
+5. **A folder is a set, not a list.** Reading a directory cannot recover the
+   order of the list that wrote it. Use `canonical()` to compare two memories,
+   and to keep git diffs to the lines that actually changed.
+6. **Round-trip or it is not the format.** `parse(serialise(m)) == m`, and
+   serialising what you parsed is byte-identical. `memfmt validate` checks
+   exactly this against a real folder.
+
+---
+
+## Why files
+
+Because the alternative is that your agent's memory lives somewhere you cannot
+read, cannot grep, cannot correct, and cannot take with you.
+
+Files give you the things a database makes hard: `git diff` on what your agent
+learned this week, a pull request when it learns something wrong, `git revert`
+when it learns something harmful, and a graph view for free. And when the tool
+that wrote them goes away, the memory does not.
+
+## Where files stop being enough
+
+Honestly: at a few hundred of them.
+
+Word overlap is the best `memfmt context` can do without embeddings, and it
+starts missing things that are phrased differently. Syncing a folder between
+machines or a team is a real problem, not a `git pull` away. Deduplicating
+facts that contradict each other needs a model.
+
+That is a server's job, and memfmt does not pretend otherwise. If you get
+there, [Mengram](https://mengram.io?utm_source=memfmt&utm_medium=readme)
+writes this format today — `mengram export markdown ./memory` hands you a tree
+this library reads — and adds the search, sync and deduplication that files
+alone cannot do. Syncing a folder back into it is not built yet.
+
+Either way the files stay yours, and if you never need a server, this library
+does not expire.
+
+---
+
+## Contributing
+
+The test suite is the specification in executable form. If you are proposing a
+change to the format, the change to `tests/test_roundtrip.py` is the proposal.
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+MIT licensed.

memfmt-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+memfmt/__init__.py,sha256=cSuLOwTzoksiq42vwcCrF0_oCexyCQ9_R2xc_Psuww8,1289
+memfmt/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+memfmt/cli.py,sha256=K32uF2DLZtiTr2XQOartQdsis_9rl0QiAbSD0HcoCfo,5584
+memfmt/model.py,sha256=247pwkLr2_I4WcqkHKhC3Rf37dGXmXCXd-SDbYdX6fU,4440
+memfmt/parse.py,sha256=HiI-kb_5pFfJIKBhnG2rk8kv0WDrO_6wHmJwYVK4V70,12086
+memfmt/serialize.py,sha256=hiPAo_FBstnaBiMj9K5qYqYBiWM5sxTh8PcjMArcJCE,10625
+memfmt-0.1.0.dist-info/METADATA,sha256=9bqQDEBZ6lx91gdUz6aoclObAssxmL10nZ9GbC6ionE,7253
+memfmt-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+memfmt-0.1.0.dist-info/entry_points.txt,sha256=fr3X4furClzzvh1HeU6fi23TS7UCGWm0E4D_WJkBrbc,43
+memfmt-0.1.0.dist-info/licenses/LICENSE,sha256=JNR_mU0FK5M85vy7kzyNjzR2YhN55sVd5M-QphfaJhI,1070
+memfmt-0.1.0.dist-info/RECORD,,

memfmt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

memfmt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memfmt = memfmt.cli:main

memfmt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Baizhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.