memory-fabric 0.4.1__py3-none-any.whl

memory_fabric/__init__.py

@@ -0,0 +1,41 @@
+"""Memory Fabric public package API."""
+
+from memory_fabric.version import __version__
+from memory_fabric.storage import (
+    doctor,
+    dream,
+    initialize_memory_fabric,
+    keyword_search,
+    propose_memory_patch,
+    read_combined_context,
+    read_section,
+    rollback,
+    status,
+    write_local_memory,
+    prepare_dream_payload,
+    apply_dream_results,
+)
+from memory_fabric.eval import (
+    evaluate_dream_quality,
+    evaluate_memory_fabric,
+    evaluate_memory_quality,
+)
+
+__all__ = [
+    "__version__",
+    "doctor",
+    "dream",
+    "evaluate_dream_quality",
+    "evaluate_memory_fabric",
+    "evaluate_memory_quality",
+    "initialize_memory_fabric",
+    "keyword_search",
+    "propose_memory_patch",
+    "read_combined_context",
+    "read_section",
+    "rollback",
+    "status",
+    "write_local_memory",
+    "prepare_dream_payload",
+    "apply_dream_results",
+]

memory_fabric/cli.py

@@ -0,0 +1,397 @@
+"""Command line interface for Memory Fabric."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from memory_fabric.version import __version__
+from memory_fabric.contracts import DreamEvalResult, EvalResult
+from memory_fabric.eval import evaluate_dream_quality, evaluate_memory_fabric
+from memory_fabric.paths import local_memory_dir
+from memory_fabric.storage import (
+    delete_memory_store,
+    doctor,
+    dream,
+    initialize_memory_fabric,
+    keyword_search,
+    list_memory_store,
+    propose_memory_patch,
+    read_memory_store,
+    rollback,
+    status,
+    write_memory_store,
+    sync_agent_rules,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if getattr(args, "debug_llm", False):
+        import os
+
+        os.environ["MEMORY_FABRIC_LLM_DEBUG"] = "1"
+
+    cwd = str(Path(args.cwd).expanduser().resolve())
+
+    from memory_fabric.llm import load_env_from_cwd
+
+    load_env_from_cwd(cwd)
+
+    try:
+        if args.command == "init":
+            init_result = initialize_memory_fabric(
+                cwd,
+                install_hooks=args.install_hooks,
+                memory_prompt=args.memory_prompt,
+            )
+            _print_result(init_result, args.json)
+            return 0
+        if args.command == "status":
+            _print_result(status(cwd), args.json)
+            return 0
+        if args.command == "doctor":
+            doctor_result = doctor(cwd)
+            _print_result(doctor_result, args.json)
+            return 0 if doctor_result["ok"] else 1
+        if args.command == "dream":
+            dream_result = asyncio.run(
+                dream(
+                    cwd,
+                    mode=args.mode,
+                    apply=args.apply,
+                    llm_rewrite=args.llm_rewrite,
+                    max_rewrite_tasks=args.max_rewrite_tasks,
+                )
+            )
+            if args.eval and args.apply:
+                dream_result["evaluation"] = asyncio.run(
+                    evaluate_dream_quality(
+                        cwd,
+                        snapshot=dream_result["snapshot"] or "latest",
+                        save_report=True,
+                        llm_review=args.llm_review,
+                    )
+                )
+            elif args.eval and not args.apply:
+                dream_result["warnings"].append(
+                    "Dream evaluation requires --apply because candidate mode does not mutate live memory."
+                )
+            _print_result(dream_result, args.json)
+            return 0
+        if args.command == "eval":
+            eval_result: EvalResult | DreamEvalResult
+            if args.dream_snapshot:
+                eval_result = asyncio.run(
+                    evaluate_dream_quality(
+                        cwd,
+                        snapshot=args.dream_snapshot,
+                        save_report=not args.no_save,
+                        llm_review=args.llm_review,
+                    )
+                )
+            else:
+                eval_result = asyncio.run(
+                    evaluate_memory_fabric(
+                        cwd,
+                        save_report=not args.no_save,
+                        llm_review=args.llm_review,
+                    )
+                )
+            _print_result(eval_result, args.json)
+            return 0 if eval_result["status"] != "fail" else 1
+        if args.command == "query":
+            query_result = keyword_search(cwd, args.query, max_results=args.max_results)
+            _print_result(query_result, args.json)
+            return 0
+        if args.command == "sync-agents":
+            sync_result = sync_agent_rules(cwd)
+            _print_result(sync_result, args.json)
+            return 0 if sync_result.get("success") else 1
+        if args.command == "sync-global":
+            memory_dir = local_memory_dir(cwd)
+            if not args.json and sys.stdin.isatty() and memory_dir.exists():
+                from memory_fabric.paths import global_memory_dir
+                from memory_fabric.storage import (
+                    _iter_markdown_files,
+                    _is_ignored_local_memory_path,
+                )
+                from memory_fabric.locking import locked_file
+                import shutil
+
+                promoted_count = 0
+                local_files = [
+                    path
+                    for path in _iter_markdown_files(memory_dir)
+                    if path.name != "index.md"
+                    and not _is_ignored_local_memory_path(memory_dir, path)
+                ]
+
+                if not local_files:
+                    print("No local memory files found to promote.")
+                    return 0
+
+                print("Interactive Global Memory Sync:")
+                print("===============================")
+                for path in local_files:
+                    rel_name = path.name
+                    choice = (
+                        input(f"Promote local/{rel_name} to global/{rel_name}? [y/N]: ")
+                        .strip()
+                        .lower()
+                    )
+                    if choice in {"y", "yes"}:
+                        target_dir = global_memory_dir()
+                        target_dir.mkdir(parents=True, exist_ok=True)
+                        target_path = target_dir / rel_name
+
+                        action = "copy"
+                        if target_path.exists():
+                            overwrite = (
+                                input(f"  global/{rel_name} already exists. Overwrite? [y/N]: ")
+                                .strip()
+                                .lower()
+                            )
+                            if overwrite in {"y", "yes"}:
+                                action = "copy"
+                            else:
+                                append = (
+                                    input(f"  Append content to global/{rel_name} instead? [y/N]: ")
+                                    .strip()
+                                    .lower()
+                                )
+                                if append in {"y", "yes"}:
+                                    action = "append"
+                                else:
+                                    action = "skip"
+
+                        if action == "copy":
+                            with locked_file(target_path):
+                                shutil.copy2(path, target_path)
+                            print(f"  -> Promoted to {target_path}")
+                            promoted_count += 1
+                        elif action == "append":
+                            from memory_fabric.frontmatter import (
+                                parse_frontmatter,
+                                dump_frontmatter,
+                            )
+
+                            with locked_file(target_path):
+                                local_meta, local_body = parse_frontmatter(
+                                    path.read_text(encoding="utf-8")
+                                )
+                                global_meta, global_body = parse_frontmatter(
+                                    target_path.read_text(encoding="utf-8")
+                                )
+                                new_body = global_body.rstrip() + "\n\n" + local_body.lstrip()
+                                global_meta["last_updated"] = local_meta.get("last_updated", "")
+                                target_path.write_text(
+                                    dump_frontmatter(global_meta, new_body), encoding="utf-8"
+                                )
+                            print(f"  -> Appended to {target_path}")
+                            promoted_count += 1
+                        else:
+                            print(f"  -> Skipped global/{rel_name}")
+
+                print(f"\nSync complete. Promoted {promoted_count} section(s) to global memory.")
+                return 0
+            else:
+                preview = propose_memory_patch(
+                    cwd,
+                    "Review local memory for durable rules before manually promoting them to global memory.",
+                )
+                _print_result(
+                    {
+                        "message": "Global sync is preview-only in v1 when non-interactive or JSON requested. Review local memory before promoting.",
+                        "preview": preview,
+                    },
+                    args.json,
+                )
+                return 0
+        if args.command == "rollback":
+            rollback_result = rollback(cwd, args.to)
+            _print_result(rollback_result, args.json)
+            return 0
+        if args.command == "store":
+            store_action = getattr(args, "store_action", None)
+            if store_action == "write":
+                tag_list = (
+                    [t.strip() for t in args.tags.split(",") if t.strip()] if args.tags else None
+                )
+                store_write_result = write_memory_store(
+                    cwd,
+                    store_path=args.store_path,
+                    content=args.content,
+                    title=args.title,
+                    tags=tag_list,
+                    priority=args.priority,
+                    mode=args.mode,
+                )
+                _print_result(store_write_result, args.json)
+                return 0
+            elif store_action == "read":
+                store_read_result = read_memory_store(cwd, store_path=args.store_path)
+                _print_result(store_read_result, args.json)
+                return 0
+            elif store_action == "list":
+                tag_list = (
+                    [t.strip() for t in args.tags.split(",") if t.strip()] if args.tags else None
+                )
+                store_list_result = list_memory_store(
+                    cwd,
+                    prefix=args.prefix,
+                    tags=tag_list,
+                    max_results=args.max_results,
+                )
+                _print_result(store_list_result, args.json)
+                return 0
+            elif store_action == "delete":
+                store_delete_result = delete_memory_store(cwd, store_path=args.store_path)
+                _print_result(store_delete_result, args.json)
+                return 0
+            else:
+                parser.parse_args(["store", "--help"])
+                return 1
+    except Exception as exc:  # noqa: BLE001 - CLI should surface all operational failures.
+        print(f"ai-memory: {exc}", file=sys.stderr)
+        return 1
+
+    parser.print_help()
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ai-memory", description="Memory Fabric CLI")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--cwd", default=".", help="Project working directory")
+    parser.add_argument("--json", action="store_true", help="Print JSON output")
+    parser.add_argument(
+        "--debug-llm", action="store_true", help="Enable LLM prompt and response logging"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    init_parser = subparsers.add_parser("init", help="Create .ai-memory scaffolding")
+    init_parser.add_argument(
+        "--install-hooks", action="store_true", help="Install opt-in git hooks"
+    )
+    init_parser.add_argument(
+        "--memory-prompt", default=None, help="Steering instructions for agent memory capture"
+    )
+    subparsers.add_parser("status", help="Show memory status")
+    subparsers.add_parser("doctor", help="Validate memory files and environment")
+
+    dream_parser = subparsers.add_parser("dream", help="Run local memory maintenance")
+    dream_parser.add_argument("--mode", choices=["light", "deep"], default="light")
+    dream_parser.add_argument(
+        "--apply", action="store_true", help="Apply candidate changes to live .ai-memory files"
+    )
+    dream_parser.add_argument(
+        "--llm-rewrite",
+        action="store_true",
+        help="Generate agent-assisted rewrite tasks from Dreaming output",
+    )
+    dream_parser.add_argument("--max-rewrite-tasks", type=int, default=5)
+    dream_parser.add_argument(
+        "--eval", action="store_true", help="Evaluate quality before and after Dreaming"
+    )
+    dream_parser.add_argument(
+        "--llm-review", action="store_true", help="Add optional qualitative LLM review notes"
+    )
+
+    eval_parser = subparsers.add_parser("eval", help="Evaluate memory and Dreaming quality")
+    eval_parser.add_argument(
+        "--llm-review", action="store_true", help="Add optional qualitative LLM review notes"
+    )
+    eval_parser.add_argument(
+        "--dream",
+        dest="dream_snapshot",
+        help="Evaluate a Dreaming run against a snapshot name or latest",
+    )
+    eval_parser.add_argument(
+        "--no-save", action="store_true", help="Do not save eval reports under .ai-memory/evals"
+    )
+
+    query_parser = subparsers.add_parser("query", help="Search memory")
+    query_parser.add_argument("query")
+    query_parser.add_argument("--max-results", type=int, default=10)
+
+    subparsers.add_parser(
+        "sync-agents",
+        help="Synchronize agent instruction files using AGENTS.md as the source of truth",
+    )
+    subparsers.add_parser("sync-global", help="Preview local-to-global promotion")
+
+    rollback_parser = subparsers.add_parser("rollback", help="Restore local memory from a snapshot")
+    rollback_parser.add_argument("--to", required=True, help="Snapshot name")
+
+    store_parser = subparsers.add_parser("store", help="Memory store operations")
+    store_subs = store_parser.add_subparsers(dest="store_action")
+
+    store_write = store_subs.add_parser("write", help="Write a store file")
+    store_write.add_argument(
+        "store_path", help="Semantic path (e.g. architecture/decisions/auth-service)"
+    )
+    store_write.add_argument("--content", required=True, help="Content to write")
+    store_write.add_argument("--title", default="", help="Title for the memory")
+    store_write.add_argument("--tags", default="", help="Comma-separated tags")
+    store_write.add_argument("--priority", choices=["high", "medium", "low"], default="medium")
+    store_write.add_argument("--mode", choices=["replace", "append"], default="replace")
+
+    store_read = store_subs.add_parser("read", help="Read a store file")
+    store_read.add_argument("store_path", help="Semantic path")
+
+    store_list = store_subs.add_parser("list", help="List store files")
+    store_list.add_argument("--prefix", default="", help="Filter by path prefix")
+    store_list.add_argument("--tags", default="", help="Comma-separated tags to filter by")
+    store_list.add_argument("--max-results", type=int, default=50)
+
+    store_delete = store_subs.add_parser("delete", help="Delete a store file")
+    store_delete.add_argument("store_path", help="Semantic path")
+
+    return parser
+
+
+def _print_result(result: Any, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+
+    if isinstance(result, list):
+        for item in result:
+            print(_format_item(item))
+        return
+
+    if isinstance(result, dict):
+        for key, value in result.items():
+            print(f"{key}: {_format_value(value)}")
+        return
+
+    print(result)
+
+
+def _format_item(item: Any) -> str:
+    if isinstance(item, dict):
+        if {"path", "line", "snippet"}.issubset(item):
+            return f"{item['path']}:{item['line']}: {item['snippet']}"
+        return json.dumps(item, ensure_ascii=False)
+    return str(item)
+
+
+def _format_value(value: Any) -> str:
+    if isinstance(value, list):
+        if not value:
+            return "[]"
+        return "\n  - " + "\n  - ".join(str(item) for item in value)
+    if isinstance(value, dict):
+        return "\n" + json.dumps(value, indent=2, ensure_ascii=False)
+    return str(value)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

memory_fabric/contracts.py

@@ -0,0 +1,212 @@
+"""Typed result contracts for Memory Fabric public APIs."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Literal
+
+# pydantic (pulled in by the optional `mcp` extra, to build tool schemas from these
+# TypedDicts) rejects typing.TypedDict on Python < 3.12 in favor of typing_extensions'
+# version. typing_extensions is only guaranteed present when `mcp` is installed (it's a
+# transitive pydantic dependency) — core-only installs on 3.11 fall back to stdlib, which
+# is fine there since pydantic never touches these types without the `mcp` extra.
+if sys.version_info >= (3, 12):
+    from typing import NotRequired, TypedDict
+else:
+    try:
+        from typing_extensions import NotRequired, TypedDict
+    except ImportError:
+        from typing import NotRequired, TypedDict
+
+
+Priority = Literal["high", "medium", "low"]
+WriteMode = Literal["append", "replace"]
+DreamMode = Literal["light", "deep"]
+
+
+class InitResult(TypedDict):
+    created: bool
+    memory_dir: str
+    files_created: list[str]
+    warnings: list[str]
+    resource_uris: NotRequired[list[str]]
+
+
+class ContextBundle(TypedDict):
+    text: str
+    included_sections: list[str]
+    omitted_sections: list[str]
+    token_budget: int
+    estimated_tokens: int
+    warnings: list[str]
+
+
+class MemorySection(TypedDict):
+    section: str
+    path: str
+    text: str
+    metadata: dict[str, Any]
+    truncated: bool
+    warnings: list[str]
+
+
+class SearchResult(TypedDict):
+    section: str
+    path: str
+    line: int
+    snippet: str
+    backend: NotRequired[str]  # 'ripgrep' | 'python' — which search backend was used
+
+
+class WriteResult(TypedDict):
+    changed: bool
+    path: str
+    redactions: int
+    warnings: list[str]
+
+
+class PatchPreview(TypedDict):
+    patch: str
+    affected_files: list[str]
+    redactions: int
+    warnings: list[str]
+
+
+class EpisodicJournalResult(TypedDict):
+    """Result returned by write_session_journal_tool."""
+
+    changed: bool
+    store_path: str
+    path: str
+    date: str
+    redactions: int
+    warnings: list[str]
+
+
+class StoreWriteResult(TypedDict):
+    changed: bool
+    path: str
+    store_path: str
+    redactions: int
+    warnings: list[str]
+
+
+class StoreReadResult(TypedDict):
+    store_path: str
+    path: str
+    text: str
+    metadata: dict[str, Any]
+    truncated: bool
+    warnings: list[str]
+
+
+class StoreEntry(TypedDict):
+    store_path: str
+    path: str
+    summary: str
+    priority: str
+    tags: list[str]
+    last_updated: str
+
+
+class StoreListResult(TypedDict):
+    entries: list[StoreEntry]
+    total: int
+    warnings: list[str]
+
+
+class DoctorResult(TypedDict):
+    ok: bool
+    errors: list[str]
+    warnings: list[str]
+    checked_files: list[str]
+
+
+class StatusResult(TypedDict):
+    cwd: str
+    memory_dir: str
+    memory_exists: bool
+    global_dir: str
+    provider_configured: bool
+    local_files: list[str]
+    memory_sizes: dict[str, dict[str, int]]
+    version: str
+
+
+class DreamResult(TypedDict):
+    changed: bool
+    snapshot: str | None
+    warnings: list[str]
+    checked_files: list[str]
+    candidate_store: str
+    patch_preview: str
+    affected_files: list[str]
+    consolidation: "DreamConsolidation"
+    rewrite_tasks: list["DreamRewriteTask"]
+    apply_required: bool
+    redactions: int
+    evaluation: NotRequired["DreamEvalResult"]
+
+
+class DreamConsolidation(TypedDict):
+    duplicates_found: int
+    lines_removed: int
+    files_touched: list[str]
+
+
+class DreamRewriteTask(TypedDict):
+    section: str
+    reason: str
+    instruction: str
+
+
+class EvalCheck(TypedDict):
+    id: str
+    status: Literal["pass", "warn", "fail"]
+    severity: Literal["info", "low", "medium", "high"]
+    message: str
+    recommendation: str
+    command: NotRequired[str]
+
+
+class EvalCategory(TypedDict):
+    name: str
+    score: int
+    status: Literal["pass", "warn", "fail"]
+    weight: int
+    checks: list[EvalCheck]
+
+
+class EvalResult(TypedDict):
+    kind: Literal["memory"]
+    generated_at: str
+    cwd: str
+    memory_dir: str
+    score: int
+    status: Literal["pass", "warn", "fail"]
+    categories: list[EvalCategory]
+    recommendations: list[str]
+    report_paths: list[str]
+    warnings: list[str]
+    llm_notes: list[str]
+
+
+class DreamEvalResult(TypedDict):
+    kind: Literal["dream"]
+    generated_at: str
+    cwd: str
+    memory_dir: str
+    baseline_snapshot: str
+    before_score: int
+    after_score: int
+    delta: int
+    score: int
+    status: Literal["pass", "warn", "fail"]
+    changed_files: list[str]
+    improvements: list[str]
+    regressions: list[str]
+    categories: list[EvalCategory]
+    recommendations: list[str]
+    report_paths: list[str]
+    warnings: list[str]
+    llm_notes: list[str]