nuramem 0.1.0__tar.gz

nuramem-0.1.0/.gitignore

@@ -0,0 +1,95 @@
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.uv-cache/
+dist/
+build/
+*.egg
+
+# Node / TypeScript
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+.next/
+.svelte-kit/
+out/
+
+# Tauri / Rust
+target/
+**/target/
+*.rs.bk
+Cargo.lock
+
+# IDE / editor
+.vscode/
+!.vscode/extensions.json
+!.vscode/settings.json.example
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Secrets / local config (NEVER commit these)
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*-credentials.json
+service-account*.json
+auth0-*.json
+gcp-key*.json
+
+# Terraform
+infra/terraform/.terraform/
+infra/terraform/*.tfstate
+infra/terraform/*.tfstate.*
+infra/terraform/*.tfvars
+!infra/terraform/*.tfvars.example
+infra/terraform/.terraform.lock.hcl
+infra/terraform/crash.log
+
+# Logs
+*.log
+logs/
+
+# Claude Code agent worktrees + local agent state (never commit)
+.claude/
+
+# Operational state (local dev only)
+.local-state/
+local-data/
+.firestore-emulator/
+.memorystore-emulator/
+
+# Build artifacts
+*.pyc
+*.so
+*.dylib
+*.dll
+
+# Documentation builds
+docs/_build/
+docs/site/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Local-only dev MCP wiring (machine-specific; never committed —
+# a localhost dev server must not ship to clones). See docs/integrations.md.
+.mcp.json

nuramem-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: nuramem
+Version: 0.1.0
+Summary: Nuramem CLI — cross-model memory from the terminal. Capture (nura save/this → server-side §15 extraction) and recall (nura search/briefing/schema) from the shell, CI, or any tool loop, with --json. Wire Nuramem's MCP server into your AI clients (nura connect) and install the memory skill (nura skill install).
+Project-URL: Homepage, https://nuramem.ai
+Project-URL: Documentation, https://nuramem.ai
+Author: LeadHash LLC
+License: Proprietary
+Keywords: cli,cross-model,llm,mcp,memory,nuramem
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: nuramem-api-server; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nuramem CLI (`nura`)
+
+Cross-model memory from the terminal. The same memory every connected AI reads —
+save, recall, and connect your assistants, without leaving the shell.
+
+## Install
+
+```sh
+curl -fsSL https://get.nuramem.ai | sh    # the universal installer
+# or, with a Python toolchain:
+uv tool install nuramem                   #  ·  pipx install nuramem  ·  uvx nuramem
+```
+
+## Use
+
+```sh
+nura login                      # sign in via the browser (loopback + PKCE)
+nura this "we picked Postgres over Drive for the data plane"   # capture
+nura search "data plane"        # recall;  nura briefing  ·  nura schema
+nura --json search "stripe"     # machine-readable, for CI / tool loops
+
+nura connect                    # wire Nuramem's MCP server into your AI clients
+nura skill install              # teach a coding assistant the memory gesture
+```
+
+- **Capture** (`save`/`this`) runs Nuramem's server-side §15 extraction.
+- **Recall** (`search`/`briefing`/`schema`) is always free.
+- **`nura connect`** safely merges a `nuramem` MCP entry into Claude Desktop,
+  Cursor, Windsurf, Gemini CLI and VS Code configs (idempotent; `--dry-run`).
+- **`nura skill install`** drops the bundled Nuramem skill into Claude Code /
+  Cursor / Codex / Windsurf.
+
+Auth precedence: `--api-url`/explicit token → `NURAMEM_TOKEN` → `NURAMEM_DEV_AUTH_TOKEN`
+→ the credential stored by `nura login`. CI/headless: set `NURAMEM_TOKEN`.
+
+Docs and connection guides: <https://nuramem.ai>.

nuramem-0.1.0/README.md

@@ -0,0 +1,36 @@
+# Nuramem CLI (`nura`)
+
+Cross-model memory from the terminal. The same memory every connected AI reads —
+save, recall, and connect your assistants, without leaving the shell.
+
+## Install
+
+```sh
+curl -fsSL https://get.nuramem.ai | sh    # the universal installer
+# or, with a Python toolchain:
+uv tool install nuramem                   #  ·  pipx install nuramem  ·  uvx nuramem
+```
+
+## Use
+
+```sh
+nura login                      # sign in via the browser (loopback + PKCE)
+nura this "we picked Postgres over Drive for the data plane"   # capture
+nura search "data plane"        # recall;  nura briefing  ·  nura schema
+nura --json search "stripe"     # machine-readable, for CI / tool loops
+
+nura connect                    # wire Nuramem's MCP server into your AI clients
+nura skill install              # teach a coding assistant the memory gesture
+```
+
+- **Capture** (`save`/`this`) runs Nuramem's server-side §15 extraction.
+- **Recall** (`search`/`briefing`/`schema`) is always free.
+- **`nura connect`** safely merges a `nuramem` MCP entry into Claude Desktop,
+  Cursor, Windsurf, Gemini CLI and VS Code configs (idempotent; `--dry-run`).
+- **`nura skill install`** drops the bundled Nuramem skill into Claude Code /
+  Cursor / Codex / Windsurf.
+
+Auth precedence: `--api-url`/explicit token → `NURAMEM_TOKEN` → `NURAMEM_DEV_AUTH_TOKEN`
+→ the credential stored by `nura login`. CI/headless: set `NURAMEM_TOKEN`.
+
+Docs and connection guides: <https://nuramem.ai>.

nuramem-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "nuramem"
+version = "0.1.0"
+description = "Nuramem CLI — cross-model memory from the terminal. Capture (nura save/this → server-side §15 extraction) and recall (nura search/briefing/schema) from the shell, CI, or any tool loop, with --json. Wire Nuramem's MCP server into your AI clients (nura connect) and install the memory skill (nura skill install)."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Proprietary" }
+authors = [{ name = "LeadHash LLC" }]
+keywords = ["nuramem", "memory", "mcp", "llm", "cross-model", "cli"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://nuramem.ai"
+Documentation = "https://nuramem.ai"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "nuramem-api-server",
+]
+
+[project.scripts]
+nura = "nuramem_cli.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nuramem_cli"]

nuramem-0.1.0/src/nuramem_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Nuramem CLI — scriptable capture + recall over the REST api-server."""
+
+from nuramem_cli.client import NuramemClient
+
+__all__ = ["NuramemClient"]

nuramem-0.1.0/src/nuramem_cli/__main__.py

@@ -0,0 +1,218 @@
+"""`nura` — the Nuramem CLI entrypoint.
+
+    nura save "text to remember"      # capture (server extracts §15 records)
+    nura search "stripe" --bucket decisions
+    nura briefing                     # session-start teaser
+    nura schema                       # the consolidated self-model
+    nura ... --json                   # machine-readable, for CI / tool loops
+
+Auth: NURAMEM_TOKEN (bearer). Endpoint: NURAMEM_API_URL (default beta).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from nuramem_cli.client import NuramemClient, resolve_base_url, resolve_token
+
+
+def _print_json(obj: Any) -> None:
+    print(json.dumps(obj, indent=2, ensure_ascii=False))
+
+
+def _err(status: int, data: dict) -> int:
+    """Render a non-2xx (or status-dict) response and return a nonzero code."""
+    detail = data.get("detail") or data.get("error") or data
+    print(f"error ({status}): {detail}", file=sys.stderr)
+    return 1
+
+
+def _is_status(data: dict, *names: str) -> bool:
+    return data.get("status") in names
+
+
+def cmd_save(client: NuramemClient, args) -> int:
+    status, data = client.ingest(args.text, source="cli", project_id=args.project)
+    if args.json:
+        _print_json(data)
+        return 0 if status < 300 else 1
+    if status >= 300:
+        return _err(status, data)
+    if _is_status(data, "upgrade_required"):
+        print(f"⤴  {data.get('detail', 'This is a paid capability — upgrade to use it.')}")
+        return 2
+    if _is_status(data, "needs_scope"):
+        print(f"?  Couldn't tell which project — candidates: {data.get('candidates')}")
+        return 3
+    if _is_status(data, "nothing_durable"):
+        print("nothing durable to save from that text.")
+        return 0
+    by = data.get("by_bucket") or {}
+    summary = ", ".join(f"{n} {b}" for b, n in by.items()) if by else f"{data.get('count', '?')} records"
+    print(f"✓ saved to Nuramem: {summary}")
+    return 0
+
+
+def cmd_search(client: NuramemClient, args) -> int:
+    status, data = client.search(args.bucket, args.query, limit=args.limit, project_id=args.project)
+    if args.json:
+        _print_json(data)
+        return 0 if status < 300 else 1
+    if status >= 300:
+        return _err(status, data)
+    results = data.get("results") or data.get("matched") or []
+    if not results:
+        print("no matches.")
+        return 0
+    for r in results:
+        line = r.get("summary") or r.get("title") or r.get("name") or json.dumps(r)
+        print(f"• {line}")
+    print(f"\n{data.get('total_matched', len(results))} match(es).")
+    return 0
+
+
+def cmd_briefing(client: NuramemClient, args) -> int:
+    status, data = client.briefing(project_id=args.project)
+    if args.json:
+        _print_json(data)
+        return 0 if status < 300 else 1
+    if status >= 300:
+        return _err(status, data)
+    print(data.get("briefing") or data.get("teaser") or json.dumps(data))
+    return 0
+
+
+def cmd_login(args) -> int:
+    from nuramem_cli.auth import login, resolve_mcp_url
+    try:
+        login(resolve_mcp_url(getattr(args, "mcp_url", None)),
+              open_browser=not args.no_browser)
+    except Exception as e:  # noqa: BLE001 — surface any flow failure cleanly
+        print(f"login failed: {e}", file=sys.stderr)
+        return 1
+    print("✓ signed in to Nuramem. The token is stored for the CLI.")
+    return 0
+
+
+def cmd_logout(args) -> int:
+    from nuramem_cli.auth import logout
+    print("signed out." if logout() else "no stored credentials.")
+    return 0
+
+
+def cmd_skill(args) -> int:
+    from nuramem_cli.skill import DEFAULT_TARGET, TARGETS, install, render_report
+    from pathlib import Path
+    if args.skill_cmd != "install":
+        print("usage: nura skill install [--client K] [--dir PATH] [--dry-run]", file=sys.stderr)
+        return 1
+    dest = Path(args.dir).expanduser() if args.dir else None
+    target = args.client or DEFAULT_TARGET
+    result = install(target, dest=dest, dry_run=args.dry_run)
+    if args.json:
+        _print_json(result)
+    else:
+        print(render_report(result, dry_run=args.dry_run))
+    return 0 if result["action"] != "unknown" else 1
+
+
+def cmd_connect(args) -> int:
+    from nuramem_cli.installer import CLIENTS, COMMAND_CLIENTS, DEFAULT_MCP_URL, connect, detected, render_report
+    url = args.mcp_url or DEFAULT_MCP_URL
+    if args.all:
+        keys = list(CLIENTS) + list(COMMAND_CLIENTS)
+    elif args.client:
+        keys = args.client
+    else:
+        keys = detected()
+        if not keys:
+            print("No MCP clients detected. Name one explicitly (--client claude-desktop) "
+                  f"or --all. Known: {', '.join(list(CLIENTS) + list(COMMAND_CLIENTS))}.",
+                  file=sys.stderr)
+            return 1
+    results = connect(keys, url, dry_run=args.dry_run)
+    if args.json:
+        _print_json({"url": url, "dry_run": args.dry_run, "results": results})
+    else:
+        print(render_report(results, url, dry_run=args.dry_run))
+    return 0 if all(r["action"] not in ("error", "unknown") for r in results) else 1
+
+
+def cmd_schema(client: NuramemClient, args) -> int:
+    status, data = client.schema(project_id=args.project)
+    if args.json:
+        _print_json(data)
+        return 0 if status < 300 else 1
+    if status >= 300:
+        return _err(status, data)
+    _print_json(data.get("self_model") or data)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="nura", description="Nuramem — your cross-model memory, from the terminal.")
+    p.add_argument("--json", action="store_true", help="Machine-readable output (for CI / tool loops).")
+    p.add_argument("--project", default=None, help="Project id to scope to (default: personal).")
+    p.add_argument("--api-url", default=None, help="Override NURAMEM_API_URL.")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("save", help="Capture text into memory (server extracts records).")
+    s.add_argument("text")
+    s.set_defaults(func=cmd_save)
+    # 'this' is an alias for 'save' (matches the nura-this gesture)
+    t = sub.add_parser("this", help="Alias for save.")
+    t.add_argument("text")
+    t.set_defaults(func=cmd_save)
+
+    q = sub.add_parser("search", help="Search a bucket of your memory.")
+    q.add_argument("query", nargs="?", default=None)
+    q.add_argument("--bucket", default="decisions",
+                   help="decisions|plans|people|references|learnings|state (default: decisions)")
+    q.add_argument("--limit", type=int, default=20)
+    q.set_defaults(func=cmd_search)
+
+    sub.add_parser("briefing", help="Session-start teaser of who you are.").set_defaults(func=cmd_briefing)
+    sub.add_parser("schema", help="The consolidated self-model.").set_defaults(func=cmd_schema)
+
+    li = sub.add_parser("login", help="Sign in via the browser (loopback + PKCE).")
+    li.add_argument("--no-browser", action="store_true", help="Print the URL instead of opening a browser.")
+    li.add_argument("--mcp-url", default=None, help="Override NURAMEM_MCP_URL.")
+    li.set_defaults(func=cmd_login, no_client=True)
+    sub.add_parser("logout", help="Remove the stored credential.").set_defaults(func=cmd_logout, no_client=True)
+
+    co = sub.add_parser("connect", help="Wire Nuramem's MCP server into your AI clients.")
+    co.add_argument("--client", action="append", default=None,
+                    help="Client key (repeatable); default: auto-detect installed clients.")
+    co.add_argument("--all", action="store_true", help="Configure every known client.")
+    co.add_argument("--dry-run", action="store_true", help="Show what would be written; change nothing.")
+    co.add_argument("--mcp-url", default=None, help="Override the MCP server URL.")
+    co.set_defaults(func=cmd_connect, no_client=True)
+
+    sk = sub.add_parser("skill", help="Install the Nuramem skill into a coding assistant.")
+    sksub = sk.add_subparsers(dest="skill_cmd", required=True)
+    ski = sksub.add_parser("install", help="Copy the skill into the assistant's skills dir.")
+    ski.add_argument("--client", default=None,
+                     help="claude-code (default) | cursor | codex | windsurf.")
+    ski.add_argument("--dir", default=None, help="Write to an explicit directory instead.")
+    ski.add_argument("--dry-run", action="store_true", help="Show what would be written; change nothing.")
+    sk.set_defaults(func=cmd_skill, no_client=True)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if getattr(args, "no_client", False):       # login / logout manage the token themselves
+        return args.func(args)
+    if not resolve_token():
+        print("Not signed in. Run `nura login`, or set NURAMEM_TOKEN "
+              "(NURAMEM_DEV_AUTH_TOKEN for local).", file=sys.stderr)
+        return 1
+    with NuramemClient(base_url=resolve_base_url(args.api_url)) as client:
+        return args.func(client, args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nuramem-0.1.0/src/nuramem_cli/auth.py

@@ -0,0 +1,164 @@
+"""`nura login` — browser auth via the existing MCP OAuth proxy (loopback + PKCE).
+
+Same RFC 8252 Authorization-Code + PKCE flow the MCP clients use (the proxy
+validates the localhost loopback redirect at OUR layer — what Auth0 won't do):
+  1. POST {mcp}/register            → the shared public client_id (RFC 7591)
+  2. open the browser to /authorize  (PKCE challenge + loopback redirect)
+  3. a one-shot localhost server catches the redirect's ?code
+  4. POST {mcp}/oauth/token          → the Auth0 access token (byte-identical to
+     what the REST api-server verifies)
+  5. store it (0600 file) for the CLI to use; NURAMEM_TOKEN still wins for CI.
+
+The OAuth endpoints live on the MCP server (NURAMEM_MCP_URL); the resulting token
+works for the REST api-server too (same Auth0 audience). Pieces are factored so
+the flow is testable without a real browser/Auth0.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import threading
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+DEFAULT_MCP_URL = "https://mcp.nuramem.ai"
+CRED_PATH = Path.home() / ".nuramem" / "credentials"
+
+
+def resolve_mcp_url(explicit: str | None = None) -> str:
+    return (explicit or os.environ.get("NURAMEM_MCP_URL") or DEFAULT_MCP_URL).rstrip("/")
+
+
+def pkce_pair() -> tuple[str, str]:
+    """(verifier, challenge) — challenge = base64url(sha256(verifier)), no pad."""
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+def build_authorize_url(base: str, client_id: str, redirect_uri: str,
+                        challenge: str, state: str) -> str:
+    q = urllib.parse.urlencode({
+        "response_type": "code", "client_id": client_id, "redirect_uri": redirect_uri,
+        "code_challenge": challenge, "code_challenge_method": "S256", "state": state})
+    return f"{base}/authorize?{q}"
+
+
+def parse_callback(query: str) -> tuple[str | None, str | None, str | None]:
+    """(code, state, error) from the loopback redirect's query string."""
+    p = urllib.parse.parse_qs(query)
+    err = (p.get("error") or [None])[0]
+    if err:
+        desc = (p.get("error_description") or [""])[0]
+        return None, (p.get("state") or [None])[0], f"{err}: {desc}".strip(": ")
+    return (p.get("code") or [None])[0], (p.get("state") or [None])[0], None
+
+
+def register_client(http: httpx.Client, base: str) -> str:
+    r = http.post(f"{base}/register", json={
+        "client_name": "Nuramem CLI",
+        "grant_types": ["authorization_code", "refresh_token"],
+        "response_types": ["code"], "token_endpoint_auth_method": "none"})
+    r.raise_for_status()
+    cid = r.json().get("client_id")
+    if not cid:
+        raise RuntimeError("registration returned no client_id")
+    return cid
+
+
+def exchange_code(http: httpx.Client, base: str, code: str, verifier: str,
+                  redirect_uri: str, client_id: str) -> dict[str, Any]:
+    r = http.post(f"{base}/oauth/token", data={
+        "grant_type": "authorization_code", "code": code, "code_verifier": verifier,
+        "redirect_uri": redirect_uri, "client_id": client_id})
+    r.raise_for_status()
+    tok = r.json()
+    if not tok.get("access_token"):
+        raise RuntimeError(f"token exchange returned no access_token: {tok}")
+    return tok
+
+
+# ── token storage (0600 file; NURAMEM_TOKEN env still takes precedence) ──
+def save_token(token: dict[str, Any]) -> None:
+    CRED_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CRED_PATH.write_text(json.dumps(token), encoding="utf-8")
+    os.chmod(CRED_PATH, 0o600)
+
+
+def load_token() -> str | None:
+    try:
+        return json.loads(CRED_PATH.read_text(encoding="utf-8")).get("access_token")
+    except Exception:
+        return None
+
+
+def logout() -> bool:
+    if CRED_PATH.exists():
+        CRED_PATH.unlink()
+        return True
+    return False
+
+
+def _make_handler(holder: dict, done: threading.Event):
+    class _Catcher(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            code, state, err = parse_callback(urllib.parse.urlparse(self.path).query)
+            holder.update(code=code, state=state, error=err)
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            msg = "Signed in to Nuramem — you can close this tab." if not err else f"Sign-in failed: {err}"
+            self.wfile.write(f"<html><body><h2>{msg}</h2></body></html>".encode())
+            done.set()
+
+        def log_message(self, *a: object) -> None:  # silence the default stderr log
+            pass
+    return _Catcher
+
+
+def login(mcp_base: str | None = None, *, open_browser: bool = True, timeout: float = 300.0,
+          http: httpx.Client | None = None,
+          on_authorize_url: Callable[[str], None] | None = None) -> dict[str, Any]:
+    """Run the full loopback+PKCE login and persist the token. Returns the token
+    dict. `on_authorize_url` overrides the browser-open (used by tests)."""
+    base = resolve_mcp_url(mcp_base)
+    own = http is None
+    http = http or httpx.Client(timeout=30.0)
+    try:
+        client_id = register_client(http, base)
+        verifier, challenge = pkce_pair()
+        state = secrets.token_urlsafe(24)
+        holder: dict[str, Any] = {}
+        done = threading.Event()
+        server = HTTPServer(("127.0.0.1", 0), _make_handler(holder, done))
+        redirect_uri = f"http://127.0.0.1:{server.server_address[1]}/callback"
+        url = build_authorize_url(base, client_id, redirect_uri, challenge, state)
+        threading.Thread(target=server.handle_request, daemon=True).start()
+        if on_authorize_url is not None:
+            on_authorize_url(url)
+        elif open_browser:
+            webbrowser.open(url)
+        else:
+            print(f"Open this URL to sign in:\n  {url}")
+        if not done.wait(timeout):
+            raise TimeoutError("login timed out waiting for the browser redirect")
+        if holder.get("error"):
+            raise RuntimeError(holder["error"])
+        if holder.get("state") != state:
+            raise RuntimeError("state mismatch — possible CSRF; aborting")
+        token = exchange_code(http, base, holder["code"], verifier, redirect_uri, client_id)
+        save_token(token)
+        return token
+    finally:
+        if own:
+            http.close()