agents-memory 0.42__py3-none-any.whl

agent_memory/__init__.py

@@ -0,0 +1,18 @@
+"""Local markdown memory — reference implementation of the agent-memory ABI."""
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["ROOT", "__version__"]
+
+
+def _engine_root() -> Path:
+    here = Path(__file__).resolve().parent
+    for path in [here, *here.parents]:
+        if (path / "abi" / "VERSION").is_file():
+            return path
+    return here.parents[2]
+
+
+ROOT = _engine_root()
+__version__ = (ROOT / "abi" / "VERSION").read_text(encoding="utf-8").strip()

agent_memory/__main__.py

@@ -0,0 +1,92 @@
+import sys
+from pathlib import Path
+
+# Bootstrap src/ on sys.path if invoked without editable install
+_SRC_DIR = str(Path(__file__).resolve().parent.parent)
+if _SRC_DIR not in sys.path:
+    sys.path.insert(0, _SRC_DIR)
+
+if hasattr(sys.stdout, "reconfigure"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+USAGE = """Usage: python -m agent_memory COMMAND [args]
+
+Commands:
+  sync             Rewrite always-on injection
+  inventory        Disk vs PROJECTS.md
+  ingest           Catalog / extract pipeline
+  consolidate      Move clone leaks into ~/.agents/memory
+  extract-openai   Filter Open AI GDPR export into staging
+  distill          Inspect staging inbox for distillation
+  mcp              stdio MCP server
+  help-json        Machine-readable CLI + injection spec
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv if argv is not None else sys.argv[1:])
+    if not args or args[0] in ("-h", "--help"):
+        print(USAGE, end="")
+        return 0 if args else 2
+    if args[0] in ("--help-json", "help-json"):
+        from .cli_help import main as help_main
+
+        return help_main(["--help-json"])
+    cmd, rest = args[0], args[1:]
+    if cmd == "sync":
+        from .sync import main as run
+
+        return run(rest)
+    if cmd == "inventory":
+        from .inventory import main as run
+
+        return run(rest)
+    if cmd == "ingest":
+        from .ingest import main as run
+
+        return run(rest)
+    if cmd == "distill":
+        from .store import get_staging_inbox
+
+        inbox = get_staging_inbox(limit=15)
+        if inbox["total"] == 0:
+            print("Staging inbox is empty (all caught up).")
+            return 0
+        print(f"Staging inbox: {inbox['total']} bullets ({inbox['shown']} shown)")
+        for group in inbox["groups"]:
+            label = group.get("source") or group.get("file")
+            extra = ""
+            if group.get("truncated"):
+                extra = f" (showing {group['count']} of {group['count']}+)"
+            print(f"\n## {label}{extra}")
+            for item in group["bullets"]:
+                title = item.get("title") or ""
+                prefix = f"[{title}] " if title else ""
+                print(f"- {prefix}{item.get('text') or item.get('bullet')}")
+        print("\nTo distill, tell your Agent: 'run memory-distill' or use the memory-distill skill.")
+        return 0
+    if cmd in ("ingest-chats", "ingest_chats"):
+        from .ingest_chats import main as run
+
+        return run()
+    if cmd == "consolidate":
+        from .consolidate import main as run
+
+        return run()
+    if cmd in ("extract-openai", "extract_openai"):
+        from .extract_openai import main as run
+
+        return run(rest)
+    if cmd in ("mcp", "mcp-server", "mcp_server"):
+        from .mcp_server import main as run
+
+        return run()
+    print(f"unknown command: {cmd}\n{USAGE}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_memory/cli_help.py

@@ -0,0 +1,166 @@
+"""Machine-readable CLI specs derived from argparse (source of truth)."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, List
+
+from . import __version__ as ABI_VERSION
+
+
+def _json_safe(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(v) for v in value]
+    return str(value)
+
+
+def _action_spec(action: argparse.Action) -> dict[str, Any] | None:
+    if action.help is argparse.SUPPRESS:
+        return None
+    if action.option_strings and action.option_strings[0] in ("-h", "--help"):
+        return None
+    if action.dest in ("help", "func"):
+        return None
+    if isinstance(action, argparse._SubParsersAction):
+        return None
+    flags = list(action.option_strings)
+    is_option = bool(flags)
+    is_flag = action.nargs == 0 or isinstance(action, argparse._StoreTrueAction)
+    spec: dict[str, Any] = {
+        "name": action.metavar or action.dest,
+        "dest": action.dest,
+        "help": action.help or "",
+        "required": bool(action.required),
+    }
+    if is_option:
+        spec["flags"] = flags
+        spec["kind"] = "flag" if is_flag else "option"
+    else:
+        spec["kind"] = "argument"
+        if action.nargs is not None:
+            spec["nargs"] = str(action.nargs)
+    default = action.default
+    if default is not argparse.SUPPRESS and default is not None:
+        spec["default"] = _json_safe(default)
+    if action.choices:
+        spec["choices"] = [_json_safe(c) for c in action.choices]
+    return spec
+
+
+def cli_spec(parser: argparse.ArgumentParser, *, name: str, description: str = "") -> dict[str, Any]:
+    options: List[dict[str, Any]] = []
+    arguments: List[dict[str, Any]] = []
+    for action in parser._actions:
+        item = _action_spec(action)
+        if not item:
+            continue
+        if item["kind"] == "argument":
+            arguments.append(item)
+        else:
+            options.append(item)
+    return {
+        "name": name,
+        "abi_version": ABI_VERSION,
+        "description": description or parser.description or "",
+        "usage": parser.format_usage().strip(),
+        "options": options,
+        "arguments": arguments,
+    }
+
+
+def injection_spec() -> dict[str, Any]:
+    return {
+        "scan_skips": [".agents", ".cursor", ".git", "node_modules"],
+        "no_empty_folders": True,
+        "generated_on_sync": [
+            {
+                "path": "~/.agents/AGENTS.md",
+                "from": ["~/.agents/memory/USER.md", "~/.agents/memory/PROJECTS.md"],
+                "edit": "Edit USER.md / PROJECTS.md, then re-run python -m agent_memory sync",
+            },
+            {
+                "path": "~/.agents/CLAUDE.md",
+                "bind": "~/.agents/AGENTS.md",
+                "edit": "Edit AGENTS.md only",
+            },
+            {
+                "path": "~/.agents/rules/<agent_rule_name>.mdc",
+                "hosts": ["~/.cursor/rules/<agent_rule_name>.mdc (bound on sync)"],
+                "config": "scan.json agent_rule_name (default user-rules.mdc)",
+            },
+            {
+                "path": "<repo>/.agents/AGENTS.md + CLAUDE.md",
+                "when": "registered project with path on disk",
+                "marker": "<!-- agent-memory-sync -->",
+                "note": "No <repo>/.cursor/ — scan skips .cursor; no empty memory subfolders",
+            },
+            {
+                "path": "<repo>/.agents/memory/README.md + staging/captured.md",
+                "when": "register_project",
+            },
+            {
+                "path": "~/.agents/skills/memory-sync/SKILL.md",
+                "also": ["host skill dirs per INSTALL.md"],
+            },
+        ],
+        "merged_on_init": [
+            {"path": "~/.cursor/mcp.json", "key": "mcpServers.agent-memory"},
+            {"path": "Zed settings.json", "key": "context_servers"},
+        ],
+        "copied_not_generated": [
+            {"path": "~/.agents/memory/LAYOUT.md", "source": "abi/LAYOUT.md in engine clone"},
+        ],
+        "marker": "<!-- agent-memory-sync -->",
+    }
+
+
+def full_spec() -> dict[str, Any]:
+    from .sync import build_parser as sync_parser
+    from .inventory import build_parser as inventory_parser
+
+    return {
+        "name": "agent-memory",
+        "abi_version": ABI_VERSION,
+        "scripts": {
+            "sync": cli_spec(sync_parser(), name="sync", description="Rewrite always-on injection for your Agent."),
+            "inventory": cli_spec(
+                inventory_parser(),
+                name="inventory",
+                description="Compare scan.json roots to PROJECTS.md.",
+            ),
+        },
+        "scripts_no_flags": {
+            "ingest": "Serial ingest: catalog (references) -> extract (staging) -> distill via MCP add_memory.",
+            "consolidate": "Move live markdown leaked into the engine clone into ~/.agents/memory.",
+            "extract-openai": "Thin wrapper: ingest extract for Open AI GDPR export (openai-export; --out = legacy JSON).",
+            "mcp": "MCP stdio server. Tools: see abi/MCP.md.",
+        },
+        "injection": injection_spec(),
+        "discover": "python -m agent_memory --help-json | python -m agent_memory sync --help-json | python -m agent_memory inventory --help-json",
+    }
+
+
+def emit_help_json(argv: list[str], parser: argparse.ArgumentParser, *, name: str, description: str = "") -> None:
+    payload = cli_spec(parser, name=name, description=description)
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+    args = list(argv if argv is not None else sys.argv[1:])
+    if "--help-json" in args:
+        print(json.dumps(full_spec(), indent=2, ensure_ascii=False))
+        return 0
+    print("Usage: python -m agent_memory --help-json", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_memory/consolidate.py

@@ -0,0 +1,22 @@
+"""Move live markdown out of the engine clone into ~/.agents/memory."""
+from __future__ import annotations
+
+import sys
+
+from .store import consolidate_repo_leaks, ensure_memory_layout
+
+
+def main() -> int:
+    ensure_memory_layout()
+    moved = consolidate_repo_leaks()
+    if not moved:
+        print("nothing to consolidate")
+        return 0
+    print(f"consolidated {len(moved)} paths:")
+    for line in moved:
+        print(f"  {line}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_memory/extract_openai.py

@@ -0,0 +1,102 @@
+"""Filter Open AI GDPR export: durable user lines → staging/ingest/openai-export/captured.md."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import tempfile
+import zipfile
+from pathlib import Path
+
+from .ingest_common import keep_user_line, scrub, write_staging
+from .ingest_config import discover_openai_exports, get_source, load_ingest
+from .ingest_extractors import extract_openai, user_messages
+
+keep_message = keep_user_line  # tests + legacy name
+
+
+def unzip_export(src: Path, dest: Path | None = None) -> Path:
+    dest = dest or Path(tempfile.gettempdir()) / "agent-memory-openai-export"
+    dest.mkdir(parents=True, exist_ok=True)
+    if src.suffix.lower() == ".zip" and src.is_file():
+        with zipfile.ZipFile(src) as zf:
+            zf.extractall(dest)
+        return dest
+    if src.is_dir():
+        return src
+    raise FileNotFoundError(f"not an Open AI GDPR export zip or folder: {src}")
+
+
+def extract_facts(root: Path) -> list[dict]:
+    rows: list[dict] = []
+    seen: set[str] = set()
+    for shard in sorted(root.glob("conversations-*.json")):
+        data = json.loads(shard.read_text(encoding="utf-8"))
+        for conv in data if isinstance(data, list) else []:
+            if not isinstance(conv, dict):
+                continue
+            title = str(conv.get("title") or "(untitled)")
+            for raw in user_messages(conv):
+                text = scrub(raw)
+                if not keep_message(title, text):
+                    continue
+                key = re.sub(r"\s+", " ", text.lower())
+                if key in seen:
+                    continue
+                seen.add(key)
+                rows.append({"title": title, "text": text[:400], "shard": shard.name})
+    return rows
+
+
+def resolve_export(path: str) -> Path:
+    if path:
+        p = Path(path).expanduser()
+        if p.exists():
+            return p
+        raise FileNotFoundError(path)
+    found = discover_openai_exports()
+    if not found:
+        raise FileNotFoundError(
+            "no Open AI GDPR export found — configure openai-export in ~/.agents/memory/ingest.json"
+        )
+    return found[0]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Filter Open AI GDPR export to ingest staging")
+    parser.add_argument("--zip", help="export zip or unpacked folder")
+    parser.add_argument("--out", help="legacy: write JSON instead of markdown staging")
+    args = parser.parse_args(argv)
+
+    if args.out:
+        src = resolve_export(args.zip or "")
+        root = unzip_export(src)
+        rows = extract_facts(root)
+        out = Path(args.out)
+        out.write_text(json.dumps(rows, indent=2, ensure_ascii=False), encoding="utf-8")
+        print(f"source {src}")
+        print(f"kept {len(rows)} user statements")
+        print(f"staging {out}")
+        return 0
+
+    cfg = load_ingest()
+    src = get_source("openai-export", cfg) or {
+        "id": "openai-export",
+        "kind": "openai-export",
+        "label": "Open AI — GDPR export",
+        "paths": [str(resolve_export(args.zip or ""))],
+        "extract": True,
+    }
+    if args.zip:
+        src = dict(src)
+        src["paths"] = [str(Path(args.zip).expanduser())]
+    lines = extract_openai(src)
+    label = str(src.get("label") or "Open AI — GDPR export")
+    path = write_staging("openai-export", label, lines)
+    print(f"kept {len(lines)} user statements")
+    print(f"staging {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_memory/ingest.py

@@ -0,0 +1,110 @@
+"""Serial ingest pipeline: catalog -> extract -> (distill via MCP add_memory)."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .ingest_catalog import run_catalog
+from .ingest_common import ingest_state_path, load_state
+from .ingest_config import list_sources, load_ingest
+from .ingest_extractors import run_extract
+from .store import ensure_memory_layout
+
+
+def cmd_catalog(_args: argparse.Namespace) -> int:
+    result = run_catalog()
+    print(f"catalog: {result['chats_index']}")
+    return 0
+
+
+def cmd_extract(args: argparse.Namespace) -> int:
+    result = run_extract(source_id=args.source or "")
+    active = 0
+    for sid, info in result.get("sources", {}).items():
+        if info.get("count", 0) > 0:
+            print(f"extract {sid}: {info['count']} bullets -> {info['staging']}")
+            active += 1
+    if active == 0:
+        print("extract: no new bullets extracted from active sources")
+    return 0
+
+
+def cmd_run(_args: argparse.Namespace) -> int:
+    run_catalog()
+    result = run_extract()
+    active_sources = [v for v in result.get("sources", {}).values() if v.get("count", 0) > 0]
+    total = sum(v["count"] for v in active_sources)
+    if total > 0:
+        print(f"run: catalog refreshed, {total} staging bullets across {len(active_sources)} sources")
+    else:
+        print("run: catalog refreshed, no new staging bullets found")
+    return 0
+
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    from .store import staging_status_summary
+
+    cfg = load_ingest()
+    state = load_state()
+    rows = []
+    for src in list_sources(cfg):
+        sid = str(src["id"])
+        entry = state.get("sources", {}).get(sid, {})
+        rows.append(
+            {
+                "id": sid,
+                "kind": src.get("kind"),
+                "catalog": src.get("catalog", True),
+                "extract": src.get("extract", True),
+                "last_catalog": entry.get("last_catalog"),
+                "last_extract": entry.get("last_extract"),
+                "catalog_count": entry.get("catalog_count"),
+                "extract_count": entry.get("extract_count"),
+                "extract_capped": entry.get("extract_capped"),
+                "extract_total_before_cap": entry.get("extract_total_before_cap"),
+                "staging": entry.get("staging"),
+            }
+        )
+    payload = {
+        "state_file": str(ingest_state_path()),
+        "staging": staging_status_summary(),
+        "sources": rows,
+    }
+    print(json.dumps(payload, indent=2))
+    if payload["staging"].get("nag"):
+        print(payload["staging"]["nag"], file=sys.stderr)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Ingest pipeline: catalog references, extract to staging, distill with MCP add_memory"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("catalog", help="Rebuild chats-index.md and entity reference cards")
+    p_extract = sub.add_parser("extract", help="Filter durable lines into staging/ingest/<id>/")
+    p_extract.add_argument("--source", help="single source id from ingest.json")
+    sub.add_parser("run", help="catalog then extract (all enabled sources)")
+    sub.add_parser("status", help="Print ingest/state.json summary")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    ensure_memory_layout()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "catalog":
+        return cmd_catalog(args)
+    if args.command == "extract":
+        return cmd_extract(args)
+    if args.command == "run":
+        return cmd_run(args)
+    if args.command == "status":
+        return cmd_status(args)
+    parser.error(f"unknown command {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())