memdsl 0.1.0__py3-none-any.whl

memdsl/__init__.py

@@ -0,0 +1,27 @@
+"""memdsl: agent memory as normative source code.
+
+A lintable, queryable memory DSL for LLM agents. Memory is written as
+`.mem` source files with named, typed, scoped declarations backed by
+evidence -- then linted like code and queried into layered evidence
+packs (MUST / SHOULD / CONTEXT / CONFLICT / MISSING) that an LLM can
+follow.
+"""
+
+from memdsl.parser import parse_file, parse_text, ParseError
+from memdsl.model import Workspace, Declaration
+from memdsl.linter import lint
+from memdsl.query import build_evidence_pack, EvidencePack
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "parse_file",
+    "parse_text",
+    "ParseError",
+    "Workspace",
+    "Declaration",
+    "lint",
+    "build_evidence_pack",
+    "EvidencePack",
+    "__version__",
+]

memdsl/cli.py

@@ -0,0 +1,89 @@
+"""memdsl command-line interface.
+
+    memdsl lint PATH...              lint memory source files
+    memdsl query PATH... -q TEXT     build an evidence pack for a query
+    memdsl explain PATH... ID        show one declaration with relations
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List
+
+from memdsl import __version__
+from memdsl.linter import has_errors, lint
+from memdsl.model import Workspace
+from memdsl.parser import ParseError
+from memdsl.query import build_evidence_pack, explain
+
+
+def _load(paths: List[str]) -> Workspace:
+    try:
+        return Workspace.load(paths)
+    except ParseError as e:
+        print(f"parse error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except OSError as e:
+        print(f"cannot read input: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def main(argv: List[str] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="memdsl",
+        description="Agent memory as normative source code.")
+    parser.add_argument("--version", action="version",
+                        version=f"memdsl {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_lint = sub.add_parser("lint", help="lint .mem files")
+    p_lint.add_argument("paths", nargs="+", help=".mem files or directories")
+    p_lint.add_argument("--strict", action="store_true",
+                        help="exit non-zero on warnings too")
+
+    p_query = sub.add_parser("query", help="query memory into an evidence pack")
+    p_query.add_argument("paths", nargs="+", help=".mem files or directories")
+    p_query.add_argument("-q", "--query", required=True, help="query text")
+    p_query.add_argument("--kind", action="append", dest="kinds",
+                         help="restrict to declaration kind (repeatable)")
+    p_query.add_argument("--subject", help="restrict to a subject symbol")
+    p_query.add_argument("--limit", type=int, default=8)
+    p_query.add_argument("--json", action="store_true", help="JSON output")
+
+    p_explain = sub.add_parser("explain", help="show one declaration")
+    p_explain.add_argument("paths", nargs="+", help=".mem files or directories")
+    p_explain.add_argument("id", help="declaration id (kind:name or name)")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "lint":
+        ws = _load(args.paths)
+        diags = lint(ws)
+        for d in diags:
+            print(d.render())
+        errors = sum(1 for d in diags if d.severity == "error")
+        warnings = sum(1 for d in diags if d.severity == "warning")
+        print(f"\n{len(ws.declarations)} declarations, "
+              f"{errors} error(s), {warnings} warning(s)")
+        if has_errors(diags) or (args.strict and warnings):
+            return 1
+        return 0
+
+    if args.command == "query":
+        ws = _load(args.paths)
+        pack = build_evidence_pack(ws, args.query, kinds=args.kinds,
+                                   subject=args.subject, limit=args.limit)
+        print(pack.render_json() if args.json else pack.render_text())
+        return 0
+
+    if args.command == "explain":
+        ws = _load(args.paths)
+        print(explain(ws, args.id))
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

memdsl/linter.py

@@ -0,0 +1,202 @@
+"""Linter: code-style diagnostics for memory source.
+
+Implements the v0.1 rule set from the spec:
+
+    unresolved_symbol           error    subject/relation target not defined
+    ambiguous_alias             warning  alias resolves to multiple entities
+    duplicate_declaration_id    error    same id declared twice
+    duplicate_declaration       warning  same kind+subject+scope+claim
+    missing_evidence            error    active long-term declaration without evidence
+    boundary_without_exception  warning  hard boundary with no exceptions list
+    type_force_mismatch         warning  preference:hard or boundary:advisory
+    stale_state                 warning  state past valid_until / as_of too old
+    unmarked_supersede_status   warning  superseded target not marked superseded
+    module_too_large            warning  module exceeds declaration budget
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+from memdsl.model import Workspace, Declaration
+
+STALE_STATE_DAYS = 180
+MODULE_MAX_DECLARATIONS = 50
+
+#: Kinds that require evidence when active (entities and open issues are exempt).
+EVIDENCE_REQUIRED_KINDS = {
+    "fact", "preference", "boundary", "principle", "decision", "state",
+}
+
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+@dataclass
+class Diagnostic:
+    code: str
+    severity: str  # 'error' | 'warning'
+    message: str
+    file: str
+    line: int
+    decl_id: Optional[str] = None
+
+    def render(self) -> str:
+        return f"{self.file}:{self.line}: {self.severity}[{self.code}] {self.message}"
+
+
+def _parse_date(value) -> Optional[_dt.date]:
+    if isinstance(value, str) and _DATE_RE.match(value.strip()):
+        try:
+            return _dt.date.fromisoformat(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def lint(ws: Workspace, today: Optional[_dt.date] = None) -> List[Diagnostic]:
+    today = today or _dt.date.today()
+    diags: List[Diagnostic] = []
+    known = ws.known_names() | ws.known_symbols()
+    superseded_targets = ws.superseded_ids()
+
+    # duplicate ids
+    seen_ids = {}
+    for d in ws.declarations:
+        if d.id in seen_ids:
+            first = seen_ids[d.id]
+            diags.append(Diagnostic(
+                "duplicate_declaration_id", "error",
+                f"'{d.id}' already declared at {first.file}:{first.line}",
+                d.file, d.line, d.id))
+        else:
+            seen_ids[d.id] = d
+
+    # duplicate content (same kind+subject+scope+claim)
+    seen_content = {}
+    for d in ws.declarations:
+        claim = d.claim_text.strip().lower()
+        if not claim:
+            continue
+        key = (d.kind, d.subject, d.scope, claim)
+        if key in seen_content and seen_content[key].id != d.id:
+            diags.append(Diagnostic(
+                "duplicate_declaration", "warning",
+                f"'{d.id}' duplicates '{seen_content[key].id}' "
+                f"(same kind/subject/scope/claim)",
+                d.file, d.line, d.id))
+        else:
+            seen_content.setdefault(key, d)
+
+    # ambiguous aliases
+    for alias, symbols in ws.alias_map().items():
+        if len(set(symbols)) > 1:
+            owners = ", ".join(sorted(set(symbols)))
+            entity = ws.by_id(sorted(set(symbols))[0])
+            diags.append(Diagnostic(
+                "ambiguous_alias", "warning",
+                f"alias '{alias}' resolves to multiple entities: {owners}",
+                entity.file if entity else "<workspace>",
+                entity.line if entity else 0))
+
+    for d in ws.declarations:
+        # unresolved subject symbol
+        subject = d.subject
+        if subject and subject not in known:
+            diags.append(Diagnostic(
+                "unresolved_symbol", "error",
+                f"subject '{subject}' is not a declared entity or known symbol",
+                d.file, d.line, d.id))
+
+        # unresolved relation targets
+        for rel, targets in d.relations().items():
+            for target in targets:
+                bare = target.split(":", 1)[-1]
+                if target not in known and bare not in known:
+                    diags.append(Diagnostic(
+                        "unresolved_symbol", "error",
+                        f"relation '{rel}' points to unknown declaration '{target}'",
+                        d.file, d.line, d.id))
+
+        # missing evidence
+        if (d.kind in EVIDENCE_REQUIRED_KINDS
+                and d.status == "active"
+                and d.evidence is None):
+            diags.append(Diagnostic(
+                "missing_evidence", "error",
+                f"active {d.kind} '{d.name}' has no evidence block "
+                f"(use status: candidate for unconfirmed memories)",
+                d.file, d.line, d.id))
+
+        # boundary without exception
+        if d.kind == "boundary" and "exceptions" not in d.fields:
+            diags.append(Diagnostic(
+                "boundary_without_exception", "warning",
+                f"boundary '{d.name}' declares no exceptions; confirm it is "
+                f"truly unconditional or add e.g. [user_explicit_override]",
+                d.file, d.line, d.id))
+
+        # type/force mismatch
+        if d.kind == "preference" and d.force == "hard":
+            diags.append(Diagnostic(
+                "type_force_mismatch", "warning",
+                f"preference '{d.name}' uses force: hard; promote it to a "
+                f"boundary or lower its force",
+                d.file, d.line, d.id))
+        if d.kind == "boundary" and d.force == "advisory":
+            diags.append(Diagnostic(
+                "type_force_mismatch", "warning",
+                f"boundary '{d.name}' uses force: advisory; demote it to a "
+                f"preference or raise its force",
+                d.file, d.line, d.id))
+
+        # stale state
+        if d.kind == "state" and d.status == "active":
+            valid_until = _parse_date(d.fields.get("valid_until"))
+            as_of = _parse_date(d.fields.get("as_of"))
+            if valid_until is not None and valid_until < today:
+                diags.append(Diagnostic(
+                    "stale_state", "warning",
+                    f"state '{d.name}' expired on {valid_until.isoformat()}",
+                    d.file, d.line, d.id))
+            elif as_of is not None and (today - as_of).days > STALE_STATE_DAYS:
+                diags.append(Diagnostic(
+                    "stale_state", "warning",
+                    f"state '{d.name}' as_of {as_of.isoformat()} is older than "
+                    f"{STALE_STATE_DAYS} days; re-confirm or supersede it",
+                    d.file, d.line, d.id))
+            if as_of is None and "as_of" not in d.fields:
+                diags.append(Diagnostic(
+                    "stale_state", "warning",
+                    f"state '{d.name}' has no as_of date; states must be datable",
+                    d.file, d.line, d.id))
+
+    # superseded targets whose status is not updated
+    for target in superseded_targets:
+        td = ws.by_id(target)
+        if td is not None and td.status not in ("superseded", "retracted", "archived"):
+            diags.append(Diagnostic(
+                "unmarked_supersede_status", "warning",
+                f"'{td.id}' is superseded by a newer declaration but its "
+                f"status is '{td.status}'; mark it status: superseded",
+                td.file, td.line, td.id))
+
+    # module size budget
+    per_module = {}
+    for d in ws.declarations:
+        per_module.setdefault(d.module or "<no module>", []).append(d)
+    for module, decls in per_module.items():
+        if len(decls) > MODULE_MAX_DECLARATIONS:
+            diags.append(Diagnostic(
+                "module_too_large", "warning",
+                f"module '{module}' has {len(decls)} declarations "
+                f"(budget {MODULE_MAX_DECLARATIONS}); split it",
+                decls[0].file, decls[0].line))
+
+    return sorted(diags, key=lambda x: (x.file, x.line, x.code))
+
+
+def has_errors(diags: List[Diagnostic]) -> bool:
+    return any(d.severity == "error" for d in diags)

memdsl/model.py

@@ -0,0 +1,184 @@
+"""Workspace model: declarations, symbol table, alias resolution."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional
+
+from memdsl.parser import Document, RawDeclaration, parse_file
+
+#: Declaration kinds understood by v0.1 typed rules. Other kinds parse
+#: fine but get no kind-specific behavior.
+CORE_KINDS = {
+    "entity", "fact", "preference", "boundary", "principle",
+    "decision", "state", "open_issue",
+}
+
+#: Relation field names recognized inside a `relations { ... }` block
+#: or as top-level fields.
+RELATION_FIELDS = {
+    "supports", "refines", "depends_on", "part_of", "supersedes",
+    "conflicts_with", "derived_from", "related_to", "revision_of",
+}
+
+ACTIVE_STATUSES = {"active"}
+EXCLUDED_STATUSES = {"superseded", "retracted", "archived"}
+
+
+@dataclass
+class Declaration:
+    kind: str
+    name: str
+    fields: dict
+    file: str
+    line: int
+    module: Optional[str] = None
+
+    @property
+    def id(self) -> str:
+        return f"{self.kind}:{self.name}"
+
+    @property
+    def status(self) -> str:
+        return str(self.fields.get("status", "active"))
+
+    @property
+    def force(self) -> Optional[str]:
+        v = self.fields.get("force")
+        return str(v) if v is not None else None
+
+    @property
+    def subject(self) -> Optional[str]:
+        v = self.fields.get("subject")
+        return str(v) if v is not None else None
+
+    @property
+    def scope(self) -> Optional[str]:
+        v = self.fields.get("scope")
+        return str(v) if v is not None else None
+
+    @property
+    def claim_text(self) -> str:
+        """The primary human-readable statement of this declaration."""
+        for key in ("claim", "rule", "decision", "pattern", "summary"):
+            v = self.fields.get(key)
+            if isinstance(v, str):
+                return v
+        return ""
+
+    @property
+    def evidence(self) -> Optional[dict]:
+        v = self.fields.get("evidence")
+        return v if isinstance(v, dict) else None
+
+    def relations(self) -> Dict[str, List[str]]:
+        """All relations declared on this declaration, normalized to lists."""
+        out: Dict[str, List[str]] = {}
+        sources = [self.fields]
+        rel_block = self.fields.get("relations")
+        if isinstance(rel_block, dict):
+            sources.append(rel_block)
+        for src in sources:
+            for key, value in src.items():
+                if key in RELATION_FIELDS:
+                    targets = value if isinstance(value, list) else [value]
+                    out.setdefault(key, []).extend(str(t) for t in targets)
+        return out
+
+    def searchable_text(self) -> str:
+        parts = [self.name.replace(".", " "), self.claim_text]
+        if self.subject:
+            parts.append(self.subject.replace(".", " "))
+        for key in ("aliases", "tags", "facets", "exceptions", "canonical_name", "about"):
+            v = self.fields.get(key)
+            if isinstance(v, list):
+                parts.extend(str(x) for x in v)
+            elif isinstance(v, str):
+                parts.append(v)
+        return " ".join(parts).lower()
+
+
+@dataclass
+class Workspace:
+    declarations: List[Declaration] = field(default_factory=list)
+    files: List[str] = field(default_factory=list)
+
+    # ---- construction ----
+
+    @classmethod
+    def load(cls, paths: Iterable[str]) -> "Workspace":
+        """Load one or more `.mem` files or directories (recursive)."""
+        ws = cls()
+        for path in paths:
+            if os.path.isdir(path):
+                for root, _dirs, names in os.walk(path):
+                    for name in sorted(names):
+                        if name.endswith(".mem"):
+                            ws.add_document(parse_file(os.path.join(root, name)))
+            else:
+                ws.add_document(parse_file(path))
+        return ws
+
+    def add_document(self, doc: Document) -> None:
+        self.files.append(doc.file)
+        for raw in doc.declarations:
+            self.declarations.append(
+                Declaration(kind=raw.kind, name=raw.name, fields=raw.fields,
+                            file=raw.file, line=raw.line, module=raw.module)
+            )
+
+    # ---- lookups ----
+
+    def by_id(self, decl_id: str) -> Optional[Declaration]:
+        for d in self.declarations:
+            if d.id == decl_id or d.name == decl_id:
+                return d
+        return None
+
+    def entities(self) -> List[Declaration]:
+        return [d for d in self.declarations if d.kind == "entity"]
+
+    def known_names(self) -> set:
+        names = set()
+        for d in self.declarations:
+            names.add(d.name)
+            names.add(d.id)
+        return names
+
+    def known_symbols(self) -> set:
+        """Entity names plus their canonical names."""
+        symbols = set()
+        for e in self.entities():
+            symbols.add(e.name)
+            cn = e.fields.get("canonical_name")
+            if isinstance(cn, str):
+                symbols.add(cn)
+        # Common implicit subjects
+        symbols.add("User")
+        return symbols
+
+    def alias_map(self) -> Dict[str, List[str]]:
+        """Lowercased alias -> list of entity symbols it may refer to."""
+        amap: Dict[str, List[str]] = {}
+        for e in self.entities():
+            aliases = e.fields.get("aliases", [])
+            if isinstance(aliases, list):
+                for a in aliases:
+                    amap.setdefault(str(a).lower(), []).append(e.name)
+        return amap
+
+    def resolve_alias(self, text: str) -> List[str]:
+        """Resolve a natural-language mention to candidate entity symbols."""
+        return self.alias_map().get(text.lower(), [])
+
+    def active(self) -> List[Declaration]:
+        return [d for d in self.declarations if d.status not in EXCLUDED_STATUSES]
+
+    def superseded_ids(self) -> set:
+        """Ids/names of declarations that a newer declaration supersedes."""
+        out = set()
+        for d in self.declarations:
+            for target in d.relations().get("supersedes", []):
+                out.add(target)
+        return out

memdsl/parser.py

@@ -0,0 +1,235 @@
+"""Parser for `.mem` source files.
+
+Grammar (v0.1):
+
+    document    := (module_stmt | use_stmt | declaration)*
+    module_stmt := 'module' DOTTED_NAME
+    use_stmt    := 'use' DOTTED_NAME
+    declaration := KIND NAME block
+    block       := '{' entry* '}'
+    entry       := FIELD ':' value | FIELD block
+    value       := STRING | ATOM | list
+    list        := '[' (value (',' value)*)? ']'
+
+ATOM covers bare identifiers, dotted symbols, numbers, dates
+(2026-06-15), and call-like scope forms such as project("Aurora"),
+which are kept verbatim as strings.
+
+Comments start with '#' and run to end of line.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional, Tuple
+
+
+class ParseError(Exception):
+    def __init__(self, message: str, file: str = "<text>", line: int = 0):
+        self.file = file
+        self.line = line
+        super().__init__(f"{file}:{line}: {message}")
+
+
+@dataclass
+class Token:
+    kind: str  # 'atom' | 'string' | 'punct'
+    value: str
+    line: int
+
+
+_PUNCT = set("{}[]:,")
+
+
+def _tokenize(text: str, file: str) -> List[Token]:
+    tokens: List[Token] = []
+    i, line = 0, 1
+    n = len(text)
+    while i < n:
+        ch = text[i]
+        if ch == "\n":
+            line += 1
+            i += 1
+        elif ch in " \t\r":
+            i += 1
+        elif ch == "#":
+            while i < n and text[i] != "\n":
+                i += 1
+        elif ch == '"':
+            start_line = line
+            i += 1
+            buf = []
+            while i < n and text[i] != '"':
+                if text[i] == "\\" and i + 1 < n:
+                    esc = text[i + 1]
+                    buf.append({"n": "\n", "t": "\t", '"': '"', "\\": "\\"}.get(esc, esc))
+                    i += 2
+                else:
+                    if text[i] == "\n":
+                        line += 1
+                    buf.append(text[i])
+                    i += 1
+            if i >= n:
+                raise ParseError("unterminated string", file, start_line)
+            i += 1
+            tokens.append(Token("string", "".join(buf), start_line))
+        elif ch in _PUNCT:
+            tokens.append(Token("punct", ch, line))
+            i += 1
+        else:
+            start = i
+            start_line = line
+            while i < n and text[i] not in " \t\r\n#" and text[i] not in _PUNCT and text[i] != '"':
+                if text[i] == "(":
+                    # call-like atom: consume until matching ')'
+                    depth = 0
+                    while i < n:
+                        if text[i] == "(":
+                            depth += 1
+                        elif text[i] == ")":
+                            depth -= 1
+                            if depth == 0:
+                                i += 1
+                                break
+                        elif text[i] == "\n":
+                            line += 1
+                        i += 1
+                    break
+                i += 1
+            atom = text[start:i]
+            if atom:
+                tokens.append(Token("atom", atom, start_line))
+    return tokens
+
+
+@dataclass
+class RawDeclaration:
+    kind: str
+    name: str
+    fields: dict  # str -> str | list | dict (nested block)
+    file: str
+    line: int
+    module: Optional[str] = None
+
+
+@dataclass
+class Document:
+    module: Optional[str]
+    uses: List[str] = field(default_factory=list)
+    declarations: List[RawDeclaration] = field(default_factory=list)
+    file: str = "<text>"
+
+
+class _Parser:
+    def __init__(self, tokens: List[Token], file: str):
+        self.tokens = tokens
+        self.file = file
+        self.pos = 0
+
+    def _peek(self) -> Optional[Token]:
+        return self.tokens[self.pos] if self.pos < len(self.tokens) else None
+
+    def _next(self) -> Token:
+        tok = self._peek()
+        if tok is None:
+            last_line = self.tokens[-1].line if self.tokens else 0
+            raise ParseError("unexpected end of file", self.file, last_line)
+        self.pos += 1
+        return tok
+
+    def _expect_punct(self, ch: str) -> Token:
+        tok = self._next()
+        if tok.kind != "punct" or tok.value != ch:
+            raise ParseError(f"expected '{ch}', got '{tok.value}'", self.file, tok.line)
+        return tok
+
+    def parse_document(self) -> Document:
+        doc = Document(module=None, file=self.file)
+        while self._peek() is not None:
+            tok = self._next()
+            if tok.kind != "atom":
+                raise ParseError(f"expected keyword or kind, got '{tok.value}'", self.file, tok.line)
+            if tok.value == "module":
+                name = self._next()
+                if name.kind != "atom":
+                    raise ParseError("expected module name", self.file, name.line)
+                doc.module = name.value
+            elif tok.value == "use":
+                name = self._next()
+                if name.kind != "atom":
+                    raise ParseError("expected symbol after 'use'", self.file, name.line)
+                doc.uses.append(name.value)
+            else:
+                kind = tok.value
+                name_tok = self._next()
+                if name_tok.kind != "atom":
+                    raise ParseError(f"expected declaration name after '{kind}'", self.file, name_tok.line)
+                fields = self._parse_block()
+                doc.declarations.append(
+                    RawDeclaration(kind=kind, name=name_tok.value, fields=fields,
+                                   file=self.file, line=tok.line)
+                )
+        for d in doc.declarations:
+            d.module = doc.module
+        return doc
+
+    def _parse_block(self) -> dict:
+        self._expect_punct("{")
+        fields: dict = {}
+        while True:
+            tok = self._peek()
+            if tok is None:
+                raise ParseError("unterminated block", self.file, self.tokens[-1].line)
+            if tok.kind == "punct" and tok.value == "}":
+                self._next()
+                return fields
+            key_tok = self._next()
+            if key_tok.kind != "atom":
+                raise ParseError(f"expected field name, got '{key_tok.value}'", self.file, key_tok.line)
+            sep = self._peek()
+            if sep is not None and sep.kind == "punct" and sep.value == ":":
+                self._next()
+                fields[key_tok.value] = self._parse_value()
+            elif sep is not None and sep.kind == "punct" and sep.value == "{":
+                fields[key_tok.value] = self._parse_block()
+            else:
+                got = sep.value if sep else "end of file"
+                raise ParseError(f"expected ':' or '{{' after '{key_tok.value}', got '{got}'",
+                                 self.file, key_tok.line)
+
+    def _parse_value(self) -> Any:
+        tok = self._peek()
+        if tok is None:
+            raise ParseError("expected value", self.file, self.tokens[-1].line)
+        if tok.kind == "punct" and tok.value == "[":
+            return self._parse_list()
+        tok = self._next()
+        if tok.kind in ("string", "atom"):
+            return tok.value
+        raise ParseError(f"unexpected value '{tok.value}'", self.file, tok.line)
+
+    def _parse_list(self) -> List[Any]:
+        self._expect_punct("[")
+        items: List[Any] = []
+        while True:
+            tok = self._peek()
+            if tok is None:
+                raise ParseError("unterminated list", self.file, self.tokens[-1].line)
+            if tok.kind == "punct" and tok.value == "]":
+                self._next()
+                return items
+            items.append(self._parse_value())
+            tok = self._peek()
+            if tok is not None and tok.kind == "punct" and tok.value == ",":
+                self._next()
+
+
+def parse_text(text: str, file: str = "<text>") -> Document:
+    """Parse `.mem` source text into a Document."""
+    return _Parser(_tokenize(text, file), file).parse_document()
+
+
+def parse_file(path: str) -> Document:
+    """Parse a `.mem` file into a Document."""
+    with open(path, "r", encoding="utf-8") as f:
+        return parse_text(f.read(), file=path)

memdsl/query.py

@@ -0,0 +1,268 @@
+"""Query executor: retrieve declarations and render a layered EvidencePack.
+
+The reference executor is deliberately simple: lowercase term overlap
+plus alias resolution, with typed layering on top. It demonstrates the
+*contract* (query in, MUST/SHOULD/CONTEXT/CONFLICT/MISSING out) --
+production systems should plug in a real retrieval backend (BM25,
+embeddings, or both) behind the same contract.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from memdsl.model import Workspace, Declaration
+
+_WORD_RE = re.compile(r"[a-z0-9_]+")
+
+_STOPWORDS = {
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "of", "to",
+    "in", "on", "at", "for", "and", "or", "not", "no", "my", "me", "i",
+    "it", "its", "this", "that", "these", "those", "do", "does", "did",
+    "how", "what", "when", "where", "which", "who", "why", "should",
+    "would", "could", "can", "will", "with", "about", "into", "over",
+    "please", "help", "going", "keep", "get", "make", "your", "you", "we",
+    "our", "us", "if", "so", "as", "by", "from", "up", "out", "any",
+}
+
+
+def _terms(text: str) -> List[str]:
+    return [t for t in _WORD_RE.findall(text.lower()) if t not in _STOPWORDS]
+
+
+@dataclass
+class ScoredDeclaration:
+    declaration: Declaration
+    score: float
+    matched_terms: List[str] = field(default_factory=list)
+
+
+@dataclass
+class EvidencePack:
+    query: str
+    must: List[Declaration] = field(default_factory=list)
+    should: List[Declaration] = field(default_factory=list)
+    context: List[ScoredDeclaration] = field(default_factory=list)
+    conflicts: List[Tuple[Declaration, str]] = field(default_factory=list)
+    missing: List[str] = field(default_factory=list)
+    resolved_subjects: List[str] = field(default_factory=list)
+
+    # ---- rendering ----
+
+    def render_text(self) -> str:
+        lines: List[str] = []
+        if self.resolved_subjects:
+            lines.append(f"# resolved subjects: {', '.join(self.resolved_subjects)}")
+        lines.append("MUST")
+        if self.must:
+            for d in self.must:
+                lines.append(f"- [{d.id}] {d.claim_text}"
+                             + (f" (exceptions: {d.fields['exceptions']})"
+                                if "exceptions" in d.fields else ""))
+        else:
+            lines.append("- (no hard boundaries apply)")
+        lines.append("")
+        lines.append("SHOULD")
+        if self.should:
+            for d in self.should:
+                lines.append(f"- [{d.id}] {d.claim_text}")
+        else:
+            lines.append("- (none)")
+        lines.append("")
+        lines.append("CONTEXT")
+        if self.context:
+            for s in self.context:
+                d = s.declaration
+                extra = ""
+                if d.kind == "state" and "as_of" in d.fields:
+                    extra = f" (as_of {d.fields['as_of']})"
+                lines.append(f"- [{d.id}] {d.claim_text}{extra}")
+        else:
+            lines.append("- (none)")
+        if self.conflicts:
+            lines.append("")
+            lines.append("CONFLICT")
+            for d, target in self.conflicts:
+                lines.append(f"- [{d.id}] conflicts_with [{target}]")
+        if self.missing:
+            lines.append("")
+            lines.append("MISSING")
+            for m in self.missing:
+                lines.append(f"- {m}")
+        return "\n".join(lines)
+
+    def render_json(self) -> str:
+        def decl(d: Declaration) -> dict:
+            return {"id": d.id, "claim": d.claim_text, "force": d.force,
+                    "scope": d.scope, "status": d.status,
+                    "file": d.file, "line": d.line}
+        return json.dumps({
+            "query": self.query,
+            "resolved_subjects": self.resolved_subjects,
+            "must": [decl(d) for d in self.must],
+            "should": [decl(d) for d in self.should],
+            "context": [dict(decl(s.declaration), score=round(s.score, 3))
+                        for s in self.context],
+            "conflicts": [{"id": d.id, "conflicts_with": t}
+                          for d, t in self.conflicts],
+            "missing": self.missing,
+        }, indent=2, ensure_ascii=False)
+
+
+def _score(decl: Declaration, query_terms: List[str],
+           subject_hits: List[str]) -> ScoredDeclaration:
+    hay = decl.searchable_text()
+    hay_terms = set(_terms(hay))
+    matched = [t for t in set(query_terms) if t in hay_terms]
+    score = float(len(matched))
+    if decl.subject and decl.subject in subject_hits:
+        score += 2.0
+        matched.append(f"subject:{decl.subject}")
+    if score > 0 and str(decl.fields.get("confidence", "")) == "high":
+        score += 0.25
+    return ScoredDeclaration(decl, score, matched)
+
+
+def build_evidence_pack(
+    ws: Workspace,
+    query: str,
+    kinds: Optional[List[str]] = None,
+    subject: Optional[str] = None,
+    limit: int = 8,
+) -> EvidencePack:
+    """Run a query against the workspace and build a layered EvidencePack."""
+    pack = EvidencePack(query=query)
+    query_terms = _terms(query)
+
+    # alias resolution: map query words/phrases to entity symbols
+    amap = ws.alias_map()
+    subject_hits: List[str] = []
+    lowered = query.lower()
+    for alias, symbols in amap.items():
+        if alias in lowered:
+            subject_hits.extend(symbols)
+    if subject:
+        subject_hits.append(subject)
+    pack.resolved_subjects = sorted(set(subject_hits))
+
+    superseded = ws.superseded_ids()
+    candidates = [
+        d for d in ws.active()
+        if d.kind != "entity"
+        and d.id not in superseded and d.name not in superseded
+        and (kinds is None or d.kind in kinds)
+        and (subject is None or d.subject == subject)
+    ]
+
+    scored = [_score(d, query_terms, subject_hits) for d in candidates]
+    hits = sorted([s for s in scored if s.score > 0],
+                  key=lambda s: -s.score)[:limit]
+    hit_ids = {s.declaration.id for s in hits}
+    hit_subjects = {s.declaration.subject for s in hits if s.declaration.subject}
+    hit_scopes = {s.declaration.scope for s in hits if s.declaration.scope}
+
+    # MUST: hard boundaries that matched, or that share subject/scope
+    # with the matched declarations, or that are global.
+    for d in ws.active():
+        if d.kind != "boundary" or d.force not in (None, "hard"):
+            continue
+        relevant = (
+            d.id in hit_ids
+            or d.scope in hit_scopes
+            or d.subject in hit_subjects
+            or d.scope == "global"
+        )
+        if relevant:
+            pack.must.append(d)
+
+    must_ids = {d.id for d in pack.must}
+
+    # SHOULD: strong preferences and active principles among the hits
+    for s in hits:
+        d = s.declaration
+        if d.id in must_ids:
+            continue
+        if (d.kind == "preference" and d.force == "strong") or d.kind == "principle":
+            pack.should.append(d)
+
+    should_ids = {d.id for d in pack.should}
+
+    # CONTEXT: everything else that matched. `open_issue` never enters
+    # CONTEXT -- unresolved questions are gaps, not facts (SPEC §7 rule 3);
+    # they surface under MISSING below.
+    for s in hits:
+        d = s.declaration
+        if d.id in must_ids or d.id in should_ids:
+            continue
+        if d.kind == "open_issue":
+            continue
+        pack.context.append(s)
+
+    # CONFLICT: declared conflicts among selected declarations
+    selected = pack.must + pack.should + [s.declaration for s in pack.context]
+    selected_ids = {d.id for d in selected} | {d.name for d in selected}
+    for d in selected:
+        for target in d.relations().get("conflicts_with", []):
+            bare = target.split(":", 1)[-1]
+            if target in selected_ids or bare in selected_ids:
+                pack.conflicts.append((d, target))
+
+    # MISSING: explicit gaps
+    if not hits:
+        pack.missing.append(f"no declarations matched query terms: {query_terms}")
+    if subject and not any(d.subject == subject for d in selected):
+        pack.missing.append(f"no declarations found for subject '{subject}'")
+    for s in scored:
+        if s.declaration.kind == "open_issue" and s.score > 0:
+            pack.missing.append(
+                f"open issue [{s.declaration.id}]: {s.declaration.claim_text}")
+
+    return pack
+
+
+def explain(ws: Workspace, decl_id: str) -> str:
+    """Render one declaration with its relations and evidence."""
+    d = ws.by_id(decl_id)
+    if d is None:
+        return f"declaration '{decl_id}' not found"
+    lines = [
+        f"{d.id}",
+        f"  file:    {d.file}:{d.line}",
+        f"  module:  {d.module or '(none)'}",
+        f"  status:  {d.status}",
+    ]
+    if d.subject:
+        lines.append(f"  subject: {d.subject}")
+    if d.force:
+        lines.append(f"  force:   {d.force}")
+    if d.scope:
+        lines.append(f"  scope:   {d.scope}")
+    if d.claim_text:
+        lines.append(f"  claim:   {d.claim_text}")
+    rels = d.relations()
+    if rels:
+        lines.append("  relations:")
+        for rel, targets in rels.items():
+            for t in targets:
+                lines.append(f"    {rel} -> {t}")
+    # reverse relations
+    reverse = []
+    for other in ws.declarations:
+        if other.id == d.id:
+            continue
+        for rel, targets in other.relations().items():
+            for t in targets:
+                if t in (d.id, d.name):
+                    reverse.append(f"    {other.id} --{rel}--> this")
+    if reverse:
+        lines.append("  referenced by:")
+        lines.extend(reverse)
+    ev = d.evidence
+    if ev:
+        lines.append("  evidence:")
+        for k, v in ev.items():
+            lines.append(f"    {k}: {v}")
+    return "\n".join(lines)

memdsl-0.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: memdsl
+Version: 0.1.0
+Summary: Agent memory as normative source code: a lintable, queryable memory DSL for LLM agents
+Author: liyuan
+License: MIT
+License-File: LICENSE
+Keywords: agent,context-engineering,dsl,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# memdsl
+
+[English](#english) | [中文](#中文)
+
+## English
+
+**Agent memory as normative source code.**
+
+Most agent memory systems store what you said. Almost none of them
+distinguish what an agent *must obey* from what it *may consider*. memdsl
+treats long-term memory as a small, typed, lintable source language —
+`.mem` files you can read, review, diff, version, and test — where a
+`boundary` is a rule to enforce, not a fact to recall.
+
+```mem
+preference schedule.deep_work_mornings {
+  subject: User
+  claim: "Prefers deep work in the morning; meetings after 2pm."
+  force: strong
+  scope: scheduling
+  evidence { source: chat quote: "Stop booking me into morning meetings." }
+}
+
+boundary privacy.no_family_in_public {
+  subject: User
+  rule: "Never include family member names or details in public-facing content."
+  force: hard
+  scope: global
+  exceptions: [user_explicit_override]
+  evidence { source: chat quote: "Anything about my family stays out of blog posts. Always." }
+}
+```
+
+The difference matters: a preference shapes suggestions; a boundary binds.
+Flat embeddings of "user said X" erase exactly this distinction, which is
+why agents violate rules their memory technically "contains".
+
+### 30 seconds: same question, one declaration apart
+
+Ask an agent to *"draft a public blog post about building Aurora as a
+working parent."* A similarity-ranked memory gives it the old chats where
+the kids' names appear — and nothing that ranks a rule above a reminiscence.
+The retrieved snippets are all just CONTEXT, so the names end up in the post:
+
+```text
+retrieved: "...shipped the sync fix after bedtime, Theo finally sleeping..."
+retrieved: "aurora beta feedback thread..."
+```
+
+With the boundary declared, the evidence pack puts the rule where it cannot
+be missed — in MUST, above every piece of context, whether or not the query
+lexically matched it:
+
+```console
+$ memdsl query examples/alex/ -q "draft a public blog post about aurora"
+MUST
+- [boundary:privacy.no_family_in_public] Never include family member names
+  or details in public-facing content. (exceptions: ['user_explicit_override'])
+
+CONTEXT
+- [state:aurora.beta_progress] Private beta with 40 testers; ...
+```
+
+Feed the pack to the LLM as context and the compliant behavior is to write
+the post *without* family details — and to be able to cite
+`boundary:privacy.no_family_in_public` as the reason. The pack is the
+prompt; the MUST layer is what changes the answer.
+
+### Lint it, query it
+
+Memory that can be wrong deserves a linter:
+
+```console
+$ memdsl lint examples/lint-demo/
+broken.mem:7:  error[unresolved_symbol]        subject 'User.Barista' is not a declared entity
+broken.mem:20: error[missing_evidence]         active fact 'home.timezone' has no evidence block
+broken.mem:28: warning[type_force_mismatch]    preference uses force: hard; promote it to a boundary
+broken.mem:41: warning[boundary_without_exception]  confirm it is truly unconditional
+broken.mem:53: warning[stale_state]            as_of 2025-11-02 is older than 180 days
+
+6 declarations, 2 error(s), 3 warning(s)
+```
+
+Queries return a **layered evidence pack**, not a hit list. Hard
+boundaries surface even when the query doesn't lexically match them;
+declared conflicts are shown, not averaged away; open issues surface as
+gaps instead of being hallucinated over:
+
+```console
+$ memdsl query examples/alex/ -q "should aurora keep the free tier"
+# resolved subjects: Project.Aurora
+MUST
+- [boundary:privacy.no_family_in_public] Never include family member names ...
+
+SHOULD
+- (none)
+
+CONTEXT
+- [decision:aurora.pricing_free_tier] Keep a permanent free tier.
+- [state:aurora.beta_progress] Private beta with 40 testers; sync is the top complaint. (as_of 2026-06-20)
+- [goal:aurora.revenue_target_2026] Reach $2k MRR from Aurora by end of 2026.
+
+CONFLICT
+- [decision:aurora.pricing_free_tier] conflicts_with [aurora.revenue_target_2026]
+
+MISSING
+- open issue [open_issue:aurora.pricing_undecided]: Paid tier pricing is undecided: $5 flat vs usage-based.
+```
+
+Feed that pack — MUST/SHOULD/CONTEXT/CONFLICT/MISSING — to your LLM as
+context. Every line carries a declaration id, so answers are citable and
+auditable back to source and evidence.
+
+### Install
+
+```console
+pip install memdsl        # or: pip install -e . from a checkout
+memdsl lint examples/alex/
+memdsl query examples/alex/ -q "plan tomorrow morning"
+memdsl explain examples/alex/ decision:aurora.db_postgres_migration
+```
+
+Zero runtime dependencies. Python 3.9+.
+
+Note: `memdsl lint examples/alex/` reports **one intentional warning** —
+Alex's `schedule.no_meetings_before_10` boundary declares no `exceptions`,
+and the linter asks you to confirm it is truly unconditional. That nudge
+is the feature; a clean run is `examples/mira/`.
+
+### What's in the box
+
+- **A tiny declarative language** (`.mem`): typed declarations
+  (`entity`, `fact`, `preference`, `boundary`, `principle`, `decision`,
+  `state`, `open_issue`) with force, scope, evidence, relations
+  (`supersedes`, `conflicts_with`, `refines`, ...), and lifecycle status.
+  Full grammar and semantics in [docs/SPEC.md](docs/SPEC.md).
+- **A linter** with ten diagnostics: dangling symbols, missing evidence,
+  ambiguous aliases, stale states, boundaries without exceptions,
+  preferences masquerading as laws, unmarked supersede chains.
+- **A query executor** implementing the EvidencePack contract, plus
+  `explain` for tracing one declaration's relations and provenance.
+- **Synthetic example personas** (`examples/`) — fictional users "Alex"
+  and "Mira" — and a deliberately broken file for the linter demo.
+
+### What memdsl is *not*
+
+- **Not a replacement for [Mem0](https://github.com/mem0ai/mem0),
+  [Zep](https://www.getzep.com/), or
+  [LangMem](https://langchain-ai.github.io/langmem/).** Those are
+  retrieval/extraction platforms. memdsl is a *source format and
+  contract* for the layer above: what memory means, how strongly it
+  binds, and how it is maintained. You could compile `.mem` files into
+  any of them.
+- **Not a retrieval engine.** The reference executor is deliberately
+  naive lexical matching — enough to demonstrate the contract. Production
+  use should plug BM25/embeddings behind the same EvidencePack interface.
+  Do not benchmark toy retrieval and conclude the format failed.
+- **Not an auto-writer.** v0.1 has no write pipeline. The spec (§10)
+  describes a gated, human-reviewed write path; automation should be
+  earned with audited metrics, not assumed.
+
+### Does the approach work?
+
+Early evidence from the private system this was extracted from
+(DigitalSelf, single-user): on a 100-question eval over the author's real
+long-term memory, DSL-structured retrieval nearly doubled top-1 precision
+against the same system's tuned RAG baseline (**0.57 vs 0.30**; hit rate
+0.67 vs 0.53). On public conversational benchmarks (LongMemEval, LoCoMo)
+it performs at parity with baselines under a retrieval-only harness whose
+target mapping is still being audited — we explicitly do *not* claim
+public-benchmark wins. Current honest costs: seconds-level query latency
+at scale in the private implementation (being moved to write-time
+compilation), and n=1 personalization. A reproducible benchmark report
+will be published separately.
+
+The interesting unmeasured dimension — and the reason this exists — is
+**compliance, not recall**: existing memory benchmarks test whether an
+agent can *find* a fact, none test whether it *respects* a boundary. A
+boundary-compliance benchmark is the roadmap's centerpiece.
+
+### Related work
+
+Typed/structured agent memory is converging fast:
+[MemIR](https://arxiv.org/abs/2605.25869) (typed memory IR, provenance-role
+separation), [Zep/Graphiti](https://www.getzep.com/) (temporal knowledge
+graphs with fact validity windows), [A-Mem](https://arxiv.org/abs/2502.12110)
+(Zettelkasten-style linked notes), [MemOS](https://arxiv.org/abs/2507.03724)
+(memory scheduling), and the `CLAUDE.md`/`AGENTS.md` culture of local,
+reviewable context files. memdsl's position in that landscape: local-first
+plain-text source, an explicit **normative layer** (force + boundaries +
+exceptions + MUST/SHOULD rendering), and code-style diagnostics as a
+first-class surface.
+
+### Roadmap
+
+- Target-mapping audit + reproducible benchmark report
+- Boundary-compliance benchmark (does the agent *respect* MUST items?)
+- Pluggable retrieval backends (BM25, embeddings) behind the EvidencePack contract
+- Module directory compilation for query planning
+- Gated write pipeline with review queue
+
+---
+
+Today, memdsl defines memory as typed, auditable source code. Future
+runtimes can navigate these declarations the way developers navigate
+code — following relations, inspecting evidence, tracing history, and
+asking for missing information instead of guessing.
+
+### License
+
+Code: [MIT](LICEN

memdsl-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+memdsl/__init__.py,sha256=gyr0Obz6_9qcojPbgCC4aReZyPKrXBMeZ7G3D1_3yP0,745
+memdsl/cli.py,sha256=slNzw4Tltz-hjtoloYane24u7vO8IOP7ANnMldmMaNc,3245
+memdsl/linter.py,sha256=5W4TwnpwQ_OlA7LiXeiSWKfe6vb2NOYqVhXlV5T8Pb4,8145
+memdsl/model.py,sha256=a9SuBSGOXsPI7AKeaZh9clIF3XdqQTfLEG23kMMTbe0,6118
+memdsl/parser.py,sha256=7zICGPEUoo93gZyJjHZwBAS1qSz5yx4fCgyB7Cx_aOk,8150
+memdsl/query.py,sha256=unsdzd4bJvvl7dkUbDaM1KSNlMwDXyiGOwSPkoal9Co,9752
+memdsl-0.1.0.dist-info/METADATA,sha256=VkcnReq5TZpe_GsySLXzoxxkzqzNv-OzJabQ-IQCXhw,9466
+memdsl-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+memdsl-0.1.0.dist-info/entry_points.txt,sha256=R2fMjKk1zYU9v-oHaWwpmXef2eilkjNerN-8qCwl-4U,43
+memdsl-0.1.0.dist-info/licenses/LICENSE,sha256=rZD-6-PAHBEUYb6QrwNRD__y7xRMFzMFygSqTrb80_U,1181
+memdsl-0.1.0.dist-info/RECORD,,

memdsl-0.1.0.dist-info/WHEEL

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

memdsl-0.1.0.dist-info/entry_points.txt

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

memdsl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 liyuan
+
+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.
+
+---
+
+The specification document (docs/SPEC.md) is licensed separately under
+CC-BY-4.0. See docs/SPEC.md for details.