mneme-code 3.1.0__tar.gz

mneme_code-3.1.0/.gitignore

@@ -0,0 +1,88 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual envs
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+*.tsbuildinfo
+
+# TypeScript
+*.js.map
+*.d.ts.map
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# OS
+Thumbs.db
+desktop.ini
+
+# mneme local
+.mneme/
+*.local.json
+vault-test/
+benchmarks/results/
+benchmarks/_runs/
+benchmarks/*/output/
+benchmarks/*/result.json
+benchmarks/*/hardware.json
+
+# Secrets
+.env.local
+.env.*.local
+secrets/
+*.key
+*.pem
+
+# Build artifacts
+*.tgz
+*.whl

mneme_code-3.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: mneme-code
+Version: 3.1.0
+Summary: Deterministic Python code-failure memory layer for mneme: redact-before-store, provenance-labelled FailureMemory, vault-ready markdown output.
+Author: Onour Impram
+License: Apache-2.0
+Keywords: code-failure,memory,mneme,redaction,traceback
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mneme-core<4,>=3.0.0
+Requires-Dist: mneme-graph>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mneme-code
+
+Deterministic Python code-failure memory for mneme. Parses CPython tracebacks
+into structured failures, renders them as vault-ground-truth markdown memories,
+and resolves stack frames to [mneme-graph](../mneme-graph) function nodes.
+
+Part of the [mneme](https://github.com/TheGoatPsy/mneme) memory engine.
+
+## What it does (v1)
+
+- **Traceback parsing.** `parse_traceback` turns a standard CPython traceback
+  into a `ParsedTraceback` (exception type, message, frames). It never raises;
+  unrecognised input returns `None`.
+- **Failure memories.** `failure_from_traceback` + `failure_to_markdown` produce
+  a markdown note the user owns, with provenance (`content_hash`, `observed_at`,
+  `trust`) and a confidence label.
+- **Frame resolution.** `resolve_frames` pairs each frame with a mneme-graph
+  `function` node when one matches, with a clean fallback to `None`.
+
+Redaction (`mneme_core.privacy.redact`) is applied to every user-derived string
+(exception message, code context, file path) before it is stored or rendered.
+No LLM, no network; library functions are pure (the caller injects timestamps).
+
+## Scope and deferrals (v1)
+
+The following are **not** implemented yet and are documented here for honesty:
+
+- Live test-runner integration.
+- Branch-aware failure tracking.
+- `AGENTS.md` procedural-memory parsing and repo runbook generation.
+- Fix-trajectory wiring: a *fix* is modelled as a `mneme-temporal` claim that
+  **supersedes** the failure memory. That lifecycle lives in `mneme-temporal`
+  and is reused, not reinvented here.
+- Non-Python tracebacks.

mneme_code-3.1.0/README.md

@@ -0,0 +1,34 @@
+# mneme-code
+
+Deterministic Python code-failure memory for mneme. Parses CPython tracebacks
+into structured failures, renders them as vault-ground-truth markdown memories,
+and resolves stack frames to [mneme-graph](../mneme-graph) function nodes.
+
+Part of the [mneme](https://github.com/TheGoatPsy/mneme) memory engine.
+
+## What it does (v1)
+
+- **Traceback parsing.** `parse_traceback` turns a standard CPython traceback
+  into a `ParsedTraceback` (exception type, message, frames). It never raises;
+  unrecognised input returns `None`.
+- **Failure memories.** `failure_from_traceback` + `failure_to_markdown` produce
+  a markdown note the user owns, with provenance (`content_hash`, `observed_at`,
+  `trust`) and a confidence label.
+- **Frame resolution.** `resolve_frames` pairs each frame with a mneme-graph
+  `function` node when one matches, with a clean fallback to `None`.
+
+Redaction (`mneme_core.privacy.redact`) is applied to every user-derived string
+(exception message, code context, file path) before it is stored or rendered.
+No LLM, no network; library functions are pure (the caller injects timestamps).
+
+## Scope and deferrals (v1)
+
+The following are **not** implemented yet and are documented here for honesty:
+
+- Live test-runner integration.
+- Branch-aware failure tracking.
+- `AGENTS.md` procedural-memory parsing and repo runbook generation.
+- Fix-trajectory wiring: a *fix* is modelled as a `mneme-temporal` claim that
+  **supersedes** the failure memory. That lifecycle lives in `mneme-temporal`
+  and is reused, not reinvented here.
+- Non-Python tracebacks.

mneme_code-3.1.0/mneme_code/__init__.py

@@ -0,0 +1,71 @@
+"""mneme-code: deterministic Python code-failure memory layer.
+
+Design invariants
+-----------------
+* No LLM, no network — pure stdlib + mneme-core + mneme-graph.
+* Redact-before-store — ``mneme_core.privacy.redact`` is applied to
+  ``exc_message``, every ``code_context``, and every ``file_path``
+  *before* any dataclass is constructed or any text is rendered.
+* Provenance on every record — ``content_hash`` (sha256 of canonical
+  redacted rendering), ``observed_at`` (injected by caller; never
+  produced inside library functions), ``trust`` (default ``"user"``),
+  and ``confidence`` (default ``"EXTRACTED"``).
+* Deterministic — same inputs always produce the same ``failure_id``
+  and ``content_hash``; no ``datetime.now()`` or ``random`` inside
+  library functions.
+* Markdown is the ground-truth artifact — ``failure_to_markdown``
+  produces a vault-ready note; the vault is the store.
+
+DEFER (not built in this version)
+----------------------------------
+* Live in-process test-runner plugin (a pytest hook). Console-output parsing
+  of pytest/unittest IS built — see ``testrun``.
+* Branch-aware failure tracking.
+* Repository runbook generation.
+* Non-Python tracebacks (JavaScript, Rust, Go, etc.).
+
+Public API
+----------
+    from mneme_code.stacktrace import Frame, ParsedTraceback, parse_traceback
+    from mneme_code.failure import FailureMemory, failure_from_traceback, failure_to_markdown
+    from mneme_code.resolve import resolve_frames
+    from mneme_code.agents import ProceduralMemory, parse_agents_md, procedural_to_markdown
+    from mneme_code.testrun import (
+        TestFailure, parse_pytest_output, parse_unittest_output, failures_from_test_output,
+    )
+    from mneme_code.trajectory import FixTrajectory, fix_from_failure, fix_to_markdown
+"""
+
+from mneme_code.agents import ProceduralMemory, parse_agents_md, procedural_to_markdown
+from mneme_code.failure import FailureMemory, failure_from_traceback, failure_to_markdown
+from mneme_code.resolve import resolve_frames
+from mneme_code.stacktrace import Frame, ParsedTraceback, parse_traceback
+from mneme_code.testrun import (
+    TestFailure,
+    failures_from_test_output,
+    parse_pytest_output,
+    parse_unittest_output,
+)
+from mneme_code.trajectory import FixTrajectory, fix_from_failure, fix_to_markdown
+
+__version__ = "0.2.0"
+__all__ = [
+    "__version__",
+    "Frame",
+    "ParsedTraceback",
+    "parse_traceback",
+    "FailureMemory",
+    "failure_from_traceback",
+    "failure_to_markdown",
+    "resolve_frames",
+    "ProceduralMemory",
+    "parse_agents_md",
+    "procedural_to_markdown",
+    "TestFailure",
+    "parse_pytest_output",
+    "parse_unittest_output",
+    "failures_from_test_output",
+    "FixTrajectory",
+    "fix_from_failure",
+    "fix_to_markdown",
+]

mneme_code-3.1.0/mneme_code/agents.py

@@ -0,0 +1,240 @@
+"""ProceduralMemory dataclass and vault-ready markdown serialization for AGENTS.md.
+
+Parses an AGENTS.md (or any conventions markdown) into structured procedural
+memories, one per level-2 (``##``) heading section.
+
+Design invariants (mirror stacktrace.py / failure.py):
+* Pure, deterministic — no clock, no random, no I/O inside parse functions.
+* Redact-before-store — ``mneme_core.privacy.redact`` is applied to heading
+  text, body text, and fenced-command text before any dataclass field is set.
+* Never raises — ``parse_agents_md`` catches all exceptions and returns ``[]``.
+* Frozen dataclasses for all public types.
+* ``procedural_to_markdown`` accepts ``created: datetime`` injected by caller.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from mneme_core.privacy import redact
+
+# ---------------------------------------------------------------------------
+# Regex helpers
+# ---------------------------------------------------------------------------
+
+# Level-2 heading: "## Some Title"  (with optional trailing whitespace)
+_H2 = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
+
+# Fenced code block: ```[lang]\n...\n```  (DOTALL so body can span lines)
+_FENCE = re.compile(r"```[^\n]*\n(.*?)```", re.DOTALL)
+
+
+# ---------------------------------------------------------------------------
+# Dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProceduralMemory:
+    """A single procedural-memory record extracted from one ## section.
+
+    All string fields have already been passed through ``redact()`` before
+    construction; callers must not bypass this by constructing
+    ``ProceduralMemory`` directly with raw user content.
+
+    Attributes:
+        memory_id     Deterministic UUID5(NAMESPACE_URL, source_path + NUL + heading).
+        title         Redacted section heading text (without the "## " prefix).
+        content       Redacted section body (prose text, fenced blocks stripped out).
+        commands      Tuple of fenced code-block contents found in the section,
+                      redacted, in document order.
+        source_path   Vault-relative posix path supplied by the caller.
+        content_hash  SHA-256 hex of ``redact(full_file_text)``.
+        trust         Provenance tier; default ``"user"``.
+        confidence    Confidence label; default ``"EXTRACTED"``.
+    """
+
+    memory_id: str
+    title: str
+    content: str
+    commands: tuple[str, ...]
+    source_path: str
+    content_hash: str
+    trust: str = field(default="user")
+    confidence: str = field(default="EXTRACTED")
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+
+def parse_agents_md(text: str, *, source_path: str) -> list[ProceduralMemory]:
+    """Parse *text* into a list of :class:`ProceduralMemory` records.
+
+    Each level-2 (``## ``) heading produces one record.  Content that appears
+    before the first ``## `` heading (including any level-1 ``# `` title line)
+    is discarded — it is typically a document title with no actionable procedure.
+
+    Edge cases:
+    * Empty string or whitespace-only → ``[]``.
+    * No ``##`` headings → ``[]``.
+    * A section with no body text and no commands → ``content=""`` / ``commands=()``.
+    * Never raises; all exceptions are swallowed and return ``[]``.
+
+    Args:
+        text:        Raw AGENTS.md file content (may be empty).
+        source_path: Vault-relative posix path to embed in each record
+                     (used for ``memory_id`` derivation and the frontmatter).
+
+    Returns:
+        Ordered list of :class:`ProceduralMemory`, one per ``##`` section.
+    """
+    try:
+        return _parse_inner(text, source_path=source_path)
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _parse_inner(text: str, *, source_path: str) -> list[ProceduralMemory]:
+    """Inner parser — may raise; wrapped by ``parse_agents_md``."""
+    if not text or not text.strip():
+        return []
+
+    # content_hash is sha256 of the redacted *full* file text.
+    content_hash = hashlib.sha256(redact(text).encode("utf-8")).hexdigest()
+
+    # Walk lines tracking fenced-code state so a "## " line INSIDE a ``` fence is
+    # treated as code, NOT as a heading (otherwise a bash comment like
+    # "## install deps" would split a phantom section). Collect (heading, body)
+    # pairs; any text before the first heading is preamble and discarded.
+    sections: list[tuple[str, str]] = []
+    current_heading: str | None = None
+    current_body: list[str] = []
+    in_fence = False
+    for line in text.splitlines():
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            if current_heading is not None:
+                current_body.append(line)
+            continue
+        if not in_fence:
+            heading_match = _H2.match(line)
+            if heading_match is not None:
+                if current_heading is not None:
+                    sections.append((current_heading, "\n".join(current_body)))
+                current_heading = heading_match.group(1).strip()
+                current_body = []
+                continue
+        if current_heading is not None:
+            current_body.append(line)
+    if current_heading is not None:
+        sections.append((current_heading, "\n".join(current_body)))
+
+    if not sections:
+        # No ## headings found.
+        return []
+
+    memories: list[ProceduralMemory] = []
+    for raw_heading, raw_body in sections:
+        # Extract fenced commands before removing them from the prose body.
+        raw_commands: list[str] = [m.group(1) for m in _FENCE.finditer(raw_body)]
+
+        # Prose content: remove fenced blocks, strip leading/trailing whitespace.
+        prose = _FENCE.sub("", raw_body).strip()
+
+        # Redact everything before storing.
+        title = redact(raw_heading)
+        content = redact(prose)
+        commands = tuple(redact(cmd) for cmd in raw_commands)
+
+        # Deterministic UUID5: namespace URL + "source_path\x00heading" (pre-redaction
+        # heading used here so identity is stable across redaction-token changes).
+        key = f"{source_path}\x00{raw_heading}"
+        memory_id = str(uuid.uuid5(uuid.NAMESPACE_URL, key))
+
+        memories.append(
+            ProceduralMemory(
+                memory_id=memory_id,
+                title=title,
+                content=content,
+                commands=commands,
+                source_path=source_path,
+                content_hash=content_hash,
+            )
+        )
+
+    return memories
+
+
+# ---------------------------------------------------------------------------
+# Markdown serializer
+# ---------------------------------------------------------------------------
+
+
+def procedural_to_markdown(mem: ProceduralMemory, *, created: datetime) -> str:
+    """Render a :class:`ProceduralMemory` as a vault-ready markdown note.
+
+    Frontmatter fields (manual construction, no yaml import — mirrors
+    ``failure_to_markdown`` style):
+        id            mem.memory_id
+        type          ``"reference"``
+        created       *created* normalised to tz-aware UTC ISO 8601 w/ microseconds
+        tags          ``["procedure", "agents-md"]``
+        source_path   JSON-encoded (safe for arbitrary vault paths)
+        content_hash  mem.content_hash
+        trust         mem.trust
+
+    Body: ``# {title}``, blank line, prose content, then (if commands are
+    present) a ``## Commands`` section with each command as a fenced block.
+
+    The *created* datetime is injected by the caller; this function never
+    calls ``datetime.now()``.  All content is already redacted upstream.
+
+    Args:
+        mem:     :class:`ProceduralMemory` to render.
+        created: Tz-aware (or naive-UTC) datetime for the ``created`` field.
+
+    Returns:
+        Vault-ready markdown string (trailing newline included).
+    """
+    # Normalise to tz-aware UTC.
+    ts = created.replace(tzinfo=UTC) if created.tzinfo is None else created.astimezone(UTC)
+    created_str = ts.isoformat(timespec="microseconds")
+
+    fm_lines = [
+        "---",
+        f"id: {mem.memory_id}",
+        "type: reference",
+        f"created: {created_str}",
+        "tags:",
+        "  - procedure",
+        "  - agents-md",
+        f"source_path: {json.dumps(mem.source_path)}",
+        f"content_hash: {mem.content_hash}",
+        f"trust: {mem.trust}",
+        "---",
+    ]
+
+    body_lines: list[str] = [
+        f"# {mem.title}",
+        "",
+        mem.content,
+    ]
+
+    if mem.commands:
+        body_lines.append("")
+        body_lines.append("## Commands")
+        body_lines.append("")
+        for cmd in mem.commands:
+            body_lines.append("```")
+            body_lines.append(cmd)
+            body_lines.append("```")
+            body_lines.append("")
+
+    return "\n".join(fm_lines) + "\n" + "\n".join(body_lines) + "\n"

mneme_code-3.1.0/mneme_code/cli.py

@@ -0,0 +1,174 @@
+"""Command-line interface for mneme-code.
+
+Subcommands
+-----------
+parse-trace [--input FILE] [--vault VAULT_ROOT] [--write] [--source LABEL]
+            [--branch NAME | --no-branch]
+    Read a CPython traceback from --input (or stdin), parse it, print a
+    redacted structured summary to stdout.  With --write, write the
+    failure_to_markdown output into
+    ``<vault>/code-failures/<failure_id>.md`` via atomic_write_text.
+    Branch-aware: the note records the vault's current git branch
+    (explicit --branch wins; --no-branch disables auto-detection).
+
+No new dependencies: argparse only (stdlib).
+
+Redaction invariant: all content is redacted by parse_traceback before
+any output or write.  The CLI may call ``datetime.now(UTC)`` — the library
+functions never do.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mneme_code.failure import failure_from_traceback, failure_to_markdown
+from mneme_code.stacktrace import parse_traceback
+
+
+def _cmd_parse_trace(args: argparse.Namespace) -> int:
+    """Implementation of the ``parse-trace`` subcommand.
+
+    Returns an exit code (0 = success, 1 = not a traceback / error).
+    """
+    # Read input.
+    input_path: str | None = getattr(args, "input", None)
+    if input_path is not None:
+        try:
+            text = Path(input_path).read_text(encoding="utf-8")
+        except OSError as exc:
+            print(f"mneme-code: cannot read input file: {exc}", file=sys.stderr)
+            return 1
+    else:
+        text = sys.stdin.read()
+
+    # Parse (redaction happens inside parse_traceback).
+    parsed = parse_traceback(text)
+    if parsed is None:
+        print("not a recognizable traceback", file=sys.stderr)
+        return 1
+
+    # Inject observed_at at the CLI boundary — the library stays pure.
+    observed_at = datetime.now(UTC)
+    source_label: str | None = getattr(args, "source", None)
+
+    failure = failure_from_traceback(parsed, observed_at=observed_at, source_label=source_label)
+
+    # Print redacted summary.
+    print(f"failure_id:   {failure.failure_id}")
+    print(f"exc_type:     {failure.exc_type}")
+    print(f"exc_message:  {failure.exc_message}")
+    print(f"frames:       {len(failure.frames)}")
+    print(f"content_hash: {failure.content_hash}")
+    if failure.source_label is not None:
+        print(f"source_label: {failure.source_label}")
+    for i, frame in enumerate(failure.frames):
+        print(f"  [{i}] {frame.file_path}:{frame.line} in {frame.function}")
+
+    # Optional vault write.
+    write: bool = getattr(args, "write", False)
+    vault_raw: str | None = getattr(args, "vault", None)
+    if write:
+        if vault_raw is None:
+            print("mneme-code: --write requires --vault", file=sys.stderr)
+            return 1
+        vault_root = Path(vault_raw).resolve()
+        out_dir = vault_root / "code-failures"
+        out_path = out_dir / f"{failure.failure_id}.md"
+        # Branch-aware failure tracking: explicit --branch wins, otherwise
+        # auto-detect from the vault's git checkout. Metadata only — the
+        # failure_id and content_hash stay branch-independent.
+        branch: str | None = getattr(args, "branch", None)
+        if branch is None and not getattr(args, "no_branch", False):
+            branch = _detect_git_branch(vault_root)
+        note = failure_to_markdown(failure, branch=branch)
+        try:
+            from mneme_core.vault.atomic_write import atomic_write_text
+
+            out_dir.mkdir(parents=True, exist_ok=True)
+            atomic_write_text(out_path, note)
+            print(f"written: {out_path}")
+        except Exception as exc:  # noqa: BLE001
+            print(f"mneme-code: write failed: {exc}", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+def _detect_git_branch(vault_root: Path) -> str | None:
+    """Current git branch of *vault_root*, or ``None`` outside a checkout."""
+    import subprocess
+
+    try:
+        proc = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=str(vault_root),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    name = proc.stdout.strip()
+    return name if proc.returncode == 0 and name else None
+
+
+def main() -> None:
+    """Entry point for the mneme-code console script."""
+    parser = argparse.ArgumentParser(
+        prog="mneme-code",
+        description="mneme-code: deterministic Python code-failure memory layer.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # parse-trace subcommand
+    pt = subparsers.add_parser(
+        "parse-trace",
+        help="Parse a CPython traceback and print a redacted summary.",
+    )
+    pt.add_argument(
+        "--input",
+        metavar="FILE",
+        default=None,
+        help="Path to a file containing the traceback text (default: stdin).",
+    )
+    pt.add_argument(
+        "--vault",
+        metavar="VAULT_ROOT",
+        default=None,
+        help="Vault root directory (required with --write).",
+    )
+    pt.add_argument(
+        "--write",
+        action="store_true",
+        default=False,
+        help="Write the failure note into <vault>/code-failures/<failure_id>.md.",
+    )
+    pt.add_argument(
+        "--source",
+        metavar="LABEL",
+        default=None,
+        help="Optional source label (e.g. 'ci-run-42').",
+    )
+    pt.add_argument(
+        "--branch",
+        metavar="NAME",
+        default=None,
+        help="Git branch recorded in the note (default: auto-detect).",
+    )
+    pt.add_argument(
+        "--no-branch",
+        action="store_true",
+        default=False,
+        help="Disable branch auto-detection.",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "parse-trace":
+        sys.exit(_cmd_parse_trace(args))