nmem-cli 0.8.3__tar.gz → 0.8.8__tar.gz

{nmem_cli-0.8.3 → nmem_cli-0.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nmem-cli
-Version: 0.8.3
+Version: 0.8.8
 Summary: CLI and TUI for Nowledge Mem - AI memory management
 Project-URL: Homepage, https://mem.nowledge.co/
 Project-URL: Repository, https://github.com/nowledge-co/

{nmem_cli-0.8.3 → nmem_cli-0.8.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nmem-cli"
-version = "0.8.3"
+version = "0.8.8"
 description = "CLI and TUI for Nowledge Mem - AI memory management"
 authors = [
     {name = "Nowledge Labs"}

{nmem_cli-0.8.3 → nmem_cli-0.8.8}/src/nmem_cli/__init__.py

@@ -20,7 +20,7 @@ Environment (overrides config file):
     NMEM_API_KEY         Optional API key (Bearer auth)
 """
 
-__version__ = "0.8.3"
+__version__ = "0.8.8"
 __author__ = "Nowledge Labs"
 
 from .cli import main

{nmem_cli-0.8.3 → nmem_cli-0.8.8}/src/nmem_cli/cli.py

@@ -33,6 +33,7 @@ from rich.prompt import Confirm, Prompt
 from rich.table import Table
 
 from . import __version__
+from .kfs_cli import handle_kfs_command, register_kfs_parser
 from .license_payload import decode_license_email
 from .session_import import SessionImportError, discover_sessions, parse_session
 
@@ -9214,6 +9215,9 @@ PRIORITY
     # stats
     subparsers.add_parser("stats", help="Show statistics")
 
+    # Knowledge Filesystem
+    register_kfs_parser(subparsers)
+
     # export / import
     export_parser = subparsers.add_parser("export", help="Export data to folder/zip (experimental)")
     export_parser.add_argument("path", help="Target export directory or .zip path")
@@ -10604,6 +10608,17 @@ def main() -> int:
             return 1
     elif cmd == "stats":
         cmd_stats()
+    elif cmd == "fs":
+        return handle_kfs_command(
+            args,
+            api_get=api_get,
+            api_post=api_post,
+            output_json=output_json,
+            is_json_mode=is_json_mode,
+            console=console,
+            print_success=print_success,
+            print_error=print_error,
+        )
     elif cmd == "export":
         cmd_export_data(
             args.path,

nmem_cli-0.8.8/src/nmem_cli/kfs_cli.py

@@ -0,0 +1,334 @@
+"""Nowledge FS commands for ``nmem fs``.
+
+The CLI module is intentionally separate from ``cli.py`` because the main
+entrypoint is already oversized.  This file owns only parser registration,
+small output shaping, and dispatch to existing ``/fs/*`` endpoints.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+ApiGet = Callable[[str, dict[str, Any] | None], dict[str, Any]]
+ApiPost = Callable[[str, dict[str, Any]], dict[str, Any]]
+
+
+def register_kfs_parser(subparsers: argparse._SubParsersAction) -> None:
+    fs = subparsers.add_parser(
+        "fs",
+        help="Nowledge FS for agents and scripts",
+        description=(
+            "Browse Mem through Nowledge FS. Paths are graph projections, "
+            "not files on disk: use ls, cat, stat, find, grep, and recall."
+        ),
+        epilog="""examples:
+  nmem fs ls /
+  nmem fs cat /wiki/entities/PostgreSQL.entity.md
+  nmem fs cat /sources/report-abc123.pdf --line 120 --lines 40
+  nmem fs find /memories --label decisions --since 2026-01-01
+  nmem fs grep "JWT rotation" /memories
+  nmem fs grep "JWT rotation" /threads --jsonl
+  nmem fs recall "session token strategy" --in /memories
+  cat note.md | nmem fs write /memories/by-id/mem-abc.memory.md --stdin""",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    fs_subs = fs.add_subparsers(dest="fs_action")
+
+    ls = fs_subs.add_parser("ls", help="List a Nowledge FS directory")
+    _add_json_flag(ls)
+    ls.add_argument("path", nargs="?", default="/")
+    ls.add_argument("-n", "--limit", type=int, default=200)
+    ls.add_argument("--cursor", help="Opaque pagination cursor")
+    ls.add_argument("-l", "--long", action="store_true", help="Show paths and hints")
+
+    cat = fs_subs.add_parser("cat", help="Read a Nowledge FS file")
+    _add_json_flag(cat)
+    cat.add_argument("path")
+    cat.add_argument("--line", type=int, help="One-based line to start reading from")
+    cat.add_argument("--lines", type=int, help="Number of lines to print")
+    cat.add_argument("--fragment", help="Fragment selector, for future format-aware reads")
+    cat.add_argument("--raw", action="store_true", help="Request raw source bytes when supported")
+    cat.add_argument("--frontmatter", action="store_true", help="Print frontmatter before body")
+
+    stat = fs_subs.add_parser("stat", help="Show metadata for a Nowledge FS path")
+    _add_json_flag(stat)
+    stat.add_argument("path")
+
+    find = fs_subs.add_parser("find", help="Structural search over Nowledge FS paths")
+    _add_json_flag(find)
+    find.add_argument("path", nargs="?", default="/memories")
+    find.add_argument("--type", choices=["memory", "crystal"], help="Filter by file type")
+    find.add_argument("--label", help="Filter by label")
+    find.add_argument("--since", help="Lower recorded-time bound")
+    find.add_argument("--until", help="Upper recorded-time bound")
+    find.add_argument("--mentions", help="Filter memories mentioning this entity")
+    find.add_argument("-n", "--limit", type=int, default=50)
+    find.add_argument("--cursor", help="Opaque pagination cursor")
+    find.add_argument("--jsonl", action="store_true", help="Print one JSON path hit per line")
+    find.add_argument("--paths", action="store_true", help="Print paths only")
+
+    grep = fs_subs.add_parser("grep", help="Literal text search")
+    _add_json_flag(grep)
+    grep.add_argument("query")
+    grep.add_argument("path", nargs="?", default="/memories")
+    grep.add_argument("-n", "--limit", type=int, default=50)
+    grep.add_argument("--cursor", help="Opaque pagination cursor")
+    grep.add_argument("--jsonl", action="store_true", help="Print one JSON match per line")
+    grep.add_argument("--paths", action="store_true", help="Print unique matched paths only")
+
+    recall = fs_subs.add_parser("recall", help="Semantic memory search returning Nowledge FS paths")
+    _add_json_flag(recall)
+    recall.add_argument("query")
+    recall.add_argument("-i", "--in", dest="path", default="/memories")
+    recall.add_argument("-k", type=int, default=20, help="Number of results")
+    recall.add_argument("--jsonl", action="store_true", help="Print one JSON path hit per line")
+    recall.add_argument("--paths", action="store_true", help="Print paths only")
+
+    write = fs_subs.add_parser("write", help="Write a canonical Nowledge FS path")
+    _add_json_flag(write)
+    write.add_argument("path")
+    body = write.add_mutually_exclusive_group(required=True)
+    body.add_argument("--body", help="Markdown body to write")
+    body.add_argument("--file", type=Path, help="Read markdown body from a local file")
+    body.add_argument("--stdin", action="store_true", help="Read markdown body from stdin")
+    write.add_argument("--frontmatter-json", help="JSON object merged into frontmatter")
+    write.add_argument("--record-version", help="Optional optimistic record version")
+
+    rm = fs_subs.add_parser("rm", help="Delete a canonical Nowledge FS path")
+    _add_json_flag(rm)
+    rm.add_argument("path")
+    rm.add_argument("-f", "--force", action="store_true", help="Skip confirmation")
+
+
+def _add_json_flag(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="JSON output",
+    )
+
+
+def handle_kfs_command(
+    args: argparse.Namespace,
+    *,
+    api_get: ApiGet,
+    api_post: ApiPost,
+    output_json: Callable[[Any], None],
+    is_json_mode: Callable[[], bool],
+    console: Any,
+    print_success: Callable[[str, str | None], None],
+    print_error: Callable[[str, str, str | None], None],
+) -> int:
+    action = getattr(args, "fs_action", None)
+    if action is None:
+        console.print("[bold]nmem fs[/bold] verbs: ls, cat, stat, find, grep, recall, write, rm")
+        return 0
+
+    if action == "ls":
+        data = api_get("/fs/ls", _params(path=args.path, limit=args.limit, cursor=args.cursor))
+        if is_json_mode():
+            output_json(data)
+        else:
+            _print_ls(console, data, long=getattr(args, "long", False))
+        return 0
+
+    if action == "cat":
+        data = api_get(
+            "/fs/cat",
+            _params(
+                path=args.path,
+                line=getattr(args, "line", None),
+                lines=getattr(args, "lines", None),
+                fragment=args.fragment,
+                raw=args.raw or None,
+            ),
+        )
+        if is_json_mode():
+            output_json(data)
+        else:
+            if getattr(args, "frontmatter", False) and data.get("frontmatter"):
+                console.print(json.dumps(data["frontmatter"], indent=2, ensure_ascii=False))
+            console.print(str(data.get("body") or ""), end="" if str(data.get("body") or "").endswith("\n") else "\n")
+        return 0
+
+    if action == "stat":
+        data = api_get("/fs/stat", {"path": args.path})
+        if is_json_mode():
+            output_json(data)
+        else:
+            _print_stat(console, data)
+        return 0
+
+    if action == "find":
+        data = api_get(
+            "/fs/find",
+            _params(
+                path=args.path,
+                type=getattr(args, "type", None),
+                label=getattr(args, "label", None),
+                since=getattr(args, "since", None),
+                until=getattr(args, "until", None),
+                mentions=getattr(args, "mentions", None),
+                limit=getattr(args, "limit", 50),
+                cursor=getattr(args, "cursor", None),
+            ),
+        )
+        return _print_hits(console, output_json, is_json_mode, data, args=args)
+
+    if action == "grep":
+        data = api_get(
+            "/fs/grep",
+            _params(path=args.path, q=args.query, limit=args.limit, cursor=args.cursor),
+        )
+        if is_json_mode():
+            output_json(data)
+        elif getattr(args, "jsonl", False):
+            _print_jsonl(data.get("matches", []) or [])
+        elif getattr(args, "paths", False):
+            _print_unique_paths(data.get("matches", []) or [])
+        else:
+            for match in data.get("matches", []) or []:
+                console.print(f"{match.get('path')}:{match.get('line', 1)}:{match.get('match', '')}")
+            _print_next_cursor(console, data)
+        return 0
+
+    if action == "recall":
+        data = api_get("/fs/recall", _params(query=args.query, path=args.path, k=args.k))
+        return _print_hits(console, output_json, is_json_mode, data, args=args)
+
+    if action == "write":
+        frontmatter = _parse_frontmatter(getattr(args, "frontmatter_json", None))
+        body = _read_body(args)
+        data = api_post(
+            "/fs/write",
+            {
+                "path": args.path,
+                "body": body,
+                "frontmatter": frontmatter,
+                "record_version": getattr(args, "record_version", None),
+            },
+        )
+        if is_json_mode():
+            output_json(data)
+        else:
+            print_success("Wrote Nowledge FS path", args.path)
+        return 0
+
+    if action == "rm":
+        if not getattr(args, "force", False) and not is_json_mode():
+            print_error(
+                "Confirmation Required",
+                "Pass --force to delete through Nowledge FS.",
+                "Only canonical writable paths can be deleted.",
+            )
+            return 1
+        data = api_post("/fs/delete", {"path": args.path})
+        if is_json_mode():
+            output_json(data)
+        else:
+            print_success("Deleted Nowledge FS path", args.path)
+        return 0
+
+    print_error("Unknown fs verb", str(action), "Run nmem fs --help.")
+    return 1
+
+
+def _params(**values: Any) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _print_ls(console: Any, data: dict[str, Any], *, long: bool) -> None:
+    for entry in data.get("entries", []) or []:
+        kind = "dir" if entry.get("kind") in {"directory", "dir"} else "file"
+        name = entry.get("name") or entry.get("path")
+        if long:
+            hint = entry.get("hint") or entry.get("updated_at") or ""
+            console.print(f"{kind:4} {entry.get('path', name)} {hint}".rstrip())
+        else:
+            suffix = "/" if kind == "dir" else ""
+            console.print(f"{name}{suffix}")
+    _print_next_cursor(console, data)
+
+
+def _print_stat(console: Any, data: dict[str, Any]) -> None:
+    for key in ("path", "kind", "type", "id", "ext", "size_bytes", "created_at", "updated_at"):
+        if key in data and data.get(key) is not None:
+            console.print(f"{key}: {data[key]}")
+    fm = data.get("frontmatter")
+    if isinstance(fm, dict) and fm:
+        console.print("frontmatter:")
+        for key, value in fm.items():
+            console.print(f"  {key}: {value}")
+
+
+def _print_hits(
+    console: Any,
+    output_json: Callable[[Any], None],
+    is_json_mode: Callable[[], bool],
+    data: dict[str, Any],
+    *,
+    args: argparse.Namespace,
+) -> int:
+    if is_json_mode():
+        output_json(data)
+    elif getattr(args, "jsonl", False):
+        _print_jsonl(data.get("paths") or data.get("hits") or [])
+    elif getattr(args, "paths", False):
+        _print_unique_paths(data.get("paths") or data.get("hits") or [])
+    else:
+        for hit in data.get("paths") or data.get("hits") or []:
+            line = str(hit.get("path") or "")
+            if hit.get("score") is not None:
+                line += f"  score={hit.get('score')}"
+            console.print(line)
+            excerpt = hit.get("excerpt") or hit.get("snippet")
+            if excerpt:
+                console.print(f"  {excerpt}")
+        _print_next_cursor(console, data)
+    return 0
+
+
+def _print_jsonl(rows: list[dict[str, Any]]) -> None:
+    for row in rows:
+        sys.stdout.write(json.dumps(row, ensure_ascii=False, separators=(",", ":")))
+        sys.stdout.write("\n")
+
+
+def _print_unique_paths(rows: list[dict[str, Any]]) -> None:
+    seen: set[str] = set()
+    for row in rows:
+        path = str(row.get("path") or "")
+        if not path or path in seen:
+            continue
+        seen.add(path)
+        sys.stdout.write(path)
+        sys.stdout.write("\n")
+
+
+def _print_next_cursor(console: Any, data: dict[str, Any]) -> None:
+    cursor = data.get("next_cursor") or data.get("nextCursor")
+    if cursor:
+        console.print(f"[dim]next cursor: {cursor}[/dim]")
+
+
+def _read_body(args: argparse.Namespace) -> str:
+    if getattr(args, "stdin", False):
+        return sys.stdin.read()
+    file_path = getattr(args, "file", None)
+    if file_path:
+        return file_path.read_text(encoding="utf-8")
+    return str(getattr(args, "body", "") or "")
+
+
+def _parse_frontmatter(raw: str | None) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    parsed = json.loads(raw)
+    if not isinstance(parsed, dict):
+        raise SystemExit("--frontmatter-json must be a JSON object")
+    return parsed