ai-memory-cli 0.1.0__tar.gz → 0.1.5__tar.gz

ai_memory_cli-0.1.5/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: ai-memory-cli
+Version: 0.1.5
+Summary: Python CLI for AI Memory terminal capture and offline sync.
+Author: AI Memory
+License-Expression: MIT
+Keywords: ai,memory,cli,terminal,rag,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AI Memory CLI
+
+Standalone Python CLI for terminal capture, hashing, offline queueing, and sync to the temporary FastAPI backend.
+
+## Install
+
+For any user machine after the package is published:
+
+```powershell
+python -m pip install ai-memory-cli
+```
+
+Before PyPI publish, install from GitHub:
+
+```powershell
+python -m pip install "ai-memory-cli @ git+https://github.com/YOUR_ORG/ai-memory-cli.git"
+```
+
+For local development from this CLI repo:
+
+```powershell
+python -m pip install -e .
+```
+
+## Basic flow
+
+```powershell
+python -m ai_memory_cli auth --token TOKEN_FROM_WEBSITE --api-url https://api.your-domain.com
+python -m ai_memory_cli init --project my-project --repo owner/repo --workspace .
+python -m ai_memory_cli workspace connect --path . --repo owner/repo --editor vscode --package-manager pip
+watch
+```
+
+`watch` is a shortcut for `python -m ai_memory_cli watch`. If Windows Device Guard blocks the generated launcher, keep using `python -m ai_memory_cli watch`.
+On Windows the shortcut is installed as `watch.cmd`; the Python Scripts folder must be on `PATH` for bare `watch` to resolve.
+
+Use `python -m ai_memory_cli run -- COMMAND` when you only want to record one command.
+
+On Windows, `python -m ai_memory_cli ...` is the safest form because it avoids PATH issues and Device Guard policies that can block pip's generated `ai-memory.exe` launcher. Also avoid angle bracket placeholders in CMD because they are treated as file redirection.
+
+Inside `watch`, type the real command you want to capture, for example `python --version`. Do not type `python -m ai_memory_cli run -- ...` inside `watch`, or you will capture the nested CLI command too.
+
+## Background agent
+
+The background agent starts at Windows logon and keeps syncing queued terminal hashes whenever the API is reachable:
+
+```powershell
+python -m ai_memory_cli agent install
+python -m ai_memory_cli agent start
+python -m ai_memory_cli agent status
+```
+
+The agent does not secretly capture every terminal on the computer. Commands are captured when they run through:
+
+```powershell
+python -m ai_memory_cli watch
+python -m ai_memory_cli run -- python --version
+```
+
+To remove the startup task:
+
+```powershell
+python -m ai_memory_cli agent stop
+python -m ai_memory_cli agent uninstall
+```
+
+Agent logs are written to `%USERPROFILE%\.ai-memory-cli\logs\agent.log`.
+
+## Storage
+
+The CLI stores config and unsynced events in a separate folder:
+
+- Windows: `%USERPROFILE%\.ai-memory-cli`
+- macOS/Linux: `~/.ai-memory-cli`
+
+Set `AI_MEMORY_CLI_HOME` to override this location.
+
+Accepted command observations are also written as plain daily hash logs:
+
+- Windows: `%USERPROFILE%\.ai-memory-cli\history\YYYY-MM-DD.log`
+- macOS/Linux: `~/.ai-memory-cli/history/YYYY-MM-DD.log`
+
+These files include time/date, event hash, command hash, output hash, source, exit code, and working-folder name. They do not store raw command text or raw output.
+
+If a command is clearly invalid, such as a pasted prompt (`ai-memory> python --version`) or a shell "not recognized" error, the CLI skips storing it as an event.
+
+## Privacy and dedupe
+
+The CLI does not send raw commands or raw output to the backend. It sends:
+
+- `command_hash`
+- `output_hash`
+- `event_hash`
+- timestamps, exit code, shell, project, repo, and local metadata
+
+If the same command produces the same output again, the CLI keeps one event hash and increments `duplicate_count`.
+
+## Excluded commands
+
+Long-running development commands are not captured by default. They still run, but no hash event is stored.
+
+Default excluded patterns include:
+
+- `npm run ...`
+- `next dev`
+- `vite`
+- `uvicorn --reload`
+- `python -m uvicorn ... --reload`
+
+Use `--include-excluded` on `run` or `watch` if you need to capture them anyway.
+
+## Publish
+
+After this folder is pushed as its own public GitHub repo, publish to PyPI with:
+
+```powershell
+.\scripts\publish.ps1 -Repository pypi
+```

ai_memory_cli-0.1.5/README.md

@@ -0,0 +1,118 @@
+# AI Memory CLI
+
+Standalone Python CLI for terminal capture, hashing, offline queueing, and sync to the temporary FastAPI backend.
+
+## Install
+
+For any user machine after the package is published:
+
+```powershell
+python -m pip install ai-memory-cli
+```
+
+Before PyPI publish, install from GitHub:
+
+```powershell
+python -m pip install "ai-memory-cli @ git+https://github.com/YOUR_ORG/ai-memory-cli.git"
+```
+
+For local development from this CLI repo:
+
+```powershell
+python -m pip install -e .
+```
+
+## Basic flow
+
+```powershell
+python -m ai_memory_cli auth --token TOKEN_FROM_WEBSITE --api-url https://api.your-domain.com
+python -m ai_memory_cli init --project my-project --repo owner/repo --workspace .
+python -m ai_memory_cli workspace connect --path . --repo owner/repo --editor vscode --package-manager pip
+watch
+```
+
+`watch` is a shortcut for `python -m ai_memory_cli watch`. If Windows Device Guard blocks the generated launcher, keep using `python -m ai_memory_cli watch`.
+On Windows the shortcut is installed as `watch.cmd`; the Python Scripts folder must be on `PATH` for bare `watch` to resolve.
+
+Use `python -m ai_memory_cli run -- COMMAND` when you only want to record one command.
+
+On Windows, `python -m ai_memory_cli ...` is the safest form because it avoids PATH issues and Device Guard policies that can block pip's generated `ai-memory.exe` launcher. Also avoid angle bracket placeholders in CMD because they are treated as file redirection.
+
+Inside `watch`, type the real command you want to capture, for example `python --version`. Do not type `python -m ai_memory_cli run -- ...` inside `watch`, or you will capture the nested CLI command too.
+
+## Background agent
+
+The background agent starts at Windows logon and keeps syncing queued terminal hashes whenever the API is reachable:
+
+```powershell
+python -m ai_memory_cli agent install
+python -m ai_memory_cli agent start
+python -m ai_memory_cli agent status
+```
+
+The agent does not secretly capture every terminal on the computer. Commands are captured when they run through:
+
+```powershell
+python -m ai_memory_cli watch
+python -m ai_memory_cli run -- python --version
+```
+
+To remove the startup task:
+
+```powershell
+python -m ai_memory_cli agent stop
+python -m ai_memory_cli agent uninstall
+```
+
+Agent logs are written to `%USERPROFILE%\.ai-memory-cli\logs\agent.log`.
+
+## Storage
+
+The CLI stores config and unsynced events in a separate folder:
+
+- Windows: `%USERPROFILE%\.ai-memory-cli`
+- macOS/Linux: `~/.ai-memory-cli`
+
+Set `AI_MEMORY_CLI_HOME` to override this location.
+
+Accepted command observations are also written as plain daily hash logs:
+
+- Windows: `%USERPROFILE%\.ai-memory-cli\history\YYYY-MM-DD.log`
+- macOS/Linux: `~/.ai-memory-cli/history/YYYY-MM-DD.log`
+
+These files include time/date, event hash, command hash, output hash, source, exit code, and working-folder name. They do not store raw command text or raw output.
+
+If a command is clearly invalid, such as a pasted prompt (`ai-memory> python --version`) or a shell "not recognized" error, the CLI skips storing it as an event.
+
+## Privacy and dedupe
+
+The CLI does not send raw commands or raw output to the backend. It sends:
+
+- `command_hash`
+- `output_hash`
+- `event_hash`
+- timestamps, exit code, shell, project, repo, and local metadata
+
+If the same command produces the same output again, the CLI keeps one event hash and increments `duplicate_count`.
+
+## Excluded commands
+
+Long-running development commands are not captured by default. They still run, but no hash event is stored.
+
+Default excluded patterns include:
+
+- `npm run ...`
+- `next dev`
+- `vite`
+- `uvicorn --reload`
+- `python -m uvicorn ... --reload`
+
+Use `--include-excluded` on `run` or `watch` if you need to capture them anyway.
+
+## Publish
+
+After this folder is pushed as its own public GitHub repo, publish to PyPI with:
+
+```powershell
+.\scripts\publish.ps1 -Repository pypi
+```

ai_memory_cli-0.1.5/bin/watch.cmd

@@ -0,0 +1,7 @@
+@echo off
+set "AI_MEMORY_PY=%~dp0python.exe"
+if exist "%AI_MEMORY_PY%" (
+  "%AI_MEMORY_PY%" -m ai_memory_cli watch %*
+) else (
+  python -m ai_memory_cli watch %*
+)

{ai_memory_cli-0.1.0 → ai_memory_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-memory-cli"
-version = "0.1.0"
+version = "0.1.5"
 description = "Python CLI for AI Memory terminal capture and offline sync."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,5 +29,8 @@ dependencies = []
 [project.scripts]
 ai-memory = "ai_memory_cli.cli:main"
 
+[tool.setuptools]
+script-files = ["bin/watch.cmd"]
+
 [tool.setuptools.packages.find]
 where = ["src"]

{ai_memory_cli-0.1.0 → ai_memory_cli-0.1.5}/src/ai_memory_cli/__init__.py

@@ -1,3 +1,3 @@
 """AI Memory terminal capture CLI."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.5"

{ai_memory_cli-0.1.0 → ai_memory_cli-0.1.5}/src/ai_memory_cli/cli.py

@@ -18,6 +18,8 @@ from typing import Any
 from . import __version__
 
 DEFAULT_API_URL = "http://127.0.0.1:8000"
+WINDOWS_AGENT_TASK_NAME = "AI Memory CLI Agent"
+DEFAULT_AGENT_INTERVAL_SECONDS = 60
 DEFAULT_EXCLUDES = [
     r"^\s*npm\s+run(\s|$)",
     r"^\s*npm\s+start(\s|$)",
@@ -30,6 +32,14 @@ DEFAULT_EXCLUDES = [
     r"uvicorn\b.*\s--reload(\s|$)",
     r"python(\.exe)?\s+-m\s+uvicorn\b.*\s--reload(\s|$)",
 ]
+SHELL_NOT_FOUND_PATTERNS = [
+    "is not recognized as an internal or external command",
+    "is not recognized as the name of a cmdlet",
+    "the system cannot find the file specified",
+    "the syntax of the command is incorrect",
+    "no such file or directory",
+    "command not found",
+]
 
 
 def utc_now() -> str:
@@ -50,7 +60,7 @@ def cli_home() -> Path:
 
 
 def ensure_dirs(home: Path) -> None:
-    for folder in ["events", "outbox", "sent", "logs"]:
+    for folder in ["events", "outbox", "sent", "logs", "history"]:
         (home / folder).mkdir(parents=True, exist_ok=True)
 
 
@@ -70,6 +80,32 @@ def write_json(path: Path, payload: Any) -> None:
     tmp_path.replace(path)
 
 
+def append_log(home: Path, message: str) -> None:
+    ensure_dirs(home)
+    log_path = home / "logs" / "agent.log"
+    with log_path.open("a", encoding="utf-8") as file:
+        file.write(f"{utc_now()} {message}\n")
+
+
+def append_history(home: Path, event: dict[str, Any], state: str) -> None:
+    ensure_dirs(home)
+    timestamp = str(event.get("observed_at") or event.get("ended_at") or utc_now())
+    day = timestamp[:10] if len(timestamp) >= 10 else utc_now()[:10]
+    history_path = home / "history" / f"{day}.log"
+    fields = [
+        timestamp,
+        f"state={state}",
+        f"source={event.get('source', '-')}",
+        f"exit={event.get('exit_code', '-')}",
+        f"event={str(event.get('event_hash', ''))[:12]}",
+        f"command_hash={event.get('command_hash', '-')}",
+        f"output_hash={event.get('output_hash', '-')}",
+        f"cwd={event.get('metadata', {}).get('cwd_tail', '-')}",
+    ]
+    with history_path.open("a", encoding="utf-8") as file:
+        file.write(" ".join(fields) + "\n")
+
+
 def config_path(home: Path) -> Path:
     return home / "config.json"
 
@@ -90,10 +126,92 @@ def save_config(home: Path, config: dict[str, Any]) -> None:
     write_json(config_path(home), config)
 
 
+def agent_state_path(home: Path) -> Path:
+    return home / "agent.json"
+
+
+def scheduler_python_executable(background: bool = True) -> str:
+    executable = Path(sys.executable)
+    if os.name == "nt" and background:
+        pythonw = executable.with_name("pythonw.exe")
+        if pythonw.exists():
+            return str(pythonw)
+    return str(executable)
+
+
+def windows_startup_dir() -> Path:
+    appdata = os.getenv("APPDATA")
+    if not appdata:
+        raise SystemExit("APPDATA is not set; cannot locate the Windows Startup folder.")
+    return Path(appdata) / "Microsoft" / "Windows" / "Start Menu" / "Programs" / "Startup"
+
+
+def windows_startup_script_path() -> Path:
+    return windows_startup_dir() / "AI Memory CLI Agent.vbs"
+
+
+def write_windows_startup_script(interval: int, limit: int) -> Path:
+    startup_dir = windows_startup_dir()
+    startup_dir.mkdir(parents=True, exist_ok=True)
+    script_path = windows_startup_script_path()
+    python_executable = scheduler_python_executable(background=False)
+    command = f'"{python_executable}" -m ai_memory_cli agent run --interval {interval} --limit {limit}'
+    escaped_command = command.replace('"', '""')
+    script_path.write_text(
+        "\n".join(
+            [
+                "Set shell = CreateObject(\"WScript.Shell\")",
+                f"shell.Run \"{escaped_command}\", 0, False",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    return script_path
+
+
+def start_detached_agent(interval: int, limit: int) -> int:
+    python_executable = scheduler_python_executable(background=True)
+    command = [
+        python_executable,
+        "-m",
+        "ai_memory_cli",
+        "agent",
+        "run",
+        "--interval",
+        str(interval),
+        "--limit",
+        str(limit),
+    ]
+    creationflags = 0
+    if os.name == "nt":
+        creationflags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        if hasattr(subprocess, "CREATE_NO_WINDOW"):
+            creationflags |= subprocess.CREATE_NO_WINDOW
+
+    process = subprocess.Popen(
+        command,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        close_fds=True,
+        creationflags=creationflags,
+    )
+    return int(process.pid)
+
+
 def normalize_command(command: str) -> str:
     return " ".join(command.strip().split())
 
 
+def clean_watch_command(command: str) -> str:
+    cleaned = command.strip()
+    while cleaned.lower().startswith("ai-memory>"):
+        cleaned = cleaned[len("ai-memory>") :].strip()
+    cleaned = re.sub(r"^[A-Za-z]:\\[^>]*>\s*", "", cleaned).strip()
+    return cleaned
+
+
 def normalize_output(stdout: str, stderr: str) -> str:
     combined = f"stdout:\n{stdout}\nstderr:\n{stderr}"
     lines = [line.rstrip() for line in combined.replace("\r\n", "\n").replace("\r", "\n").split("\n")]
@@ -123,6 +241,13 @@ def is_excluded(command: str, config: dict[str, Any]) -> bool:
     return any(re.search(pattern, command, flags=re.IGNORECASE) for pattern in patterns)
 
 
+def is_shell_not_found(stdout: str, stderr: str, exit_code: int | None) -> bool:
+    if exit_code in (None, 0):
+        return False
+    combined = f"{stdout}\n{stderr}".lower()
+    return any(pattern in combined for pattern in SHELL_NOT_FOUND_PATTERNS)
+
+
 def api_url(config: dict[str, Any]) -> str:
     return str(config.get("api_url") or DEFAULT_API_URL).rstrip("/")
 
@@ -130,7 +255,7 @@ def api_url(config: dict[str, Any]) -> str:
 def require_token(config: dict[str, Any]) -> str:
     token = str(config.get("token") or "").strip()
     if not token:
-        raise SystemExit("Run ai-memory auth --token <app-issued-cli-token> first.")
+        raise SystemExit("Run python -m ai_memory_cli auth --token TOKEN_FROM_WEBSITE first.")
     return token
 
 
@@ -261,7 +386,7 @@ def sync_events(home: Path, config: dict[str, Any], limit: int = 50, quiet: bool
     token = str(config.get("token") or "").strip()
     if not token:
         if not quiet:
-            print("No CLI token saved. Events remain queued until ai-memory auth is configured.")
+            print("No CLI token saved. Events remain queued until python -m ai_memory_cli auth is configured.")
         return 0
     paths = sorted((home / "outbox").glob("*.json"))[:limit]
     if not paths:
@@ -322,6 +447,10 @@ def capture_command(home: Path, config: dict[str, Any], command: str, include_ex
     if completed.stderr:
         print(completed.stderr, end="", file=sys.stderr)
 
+    if is_shell_not_found(completed.stdout or "", completed.stderr or "", completed.returncode):
+        print("ai-memory: skipped invalid command; nothing was stored.")
+        return completed.returncode
+
     event = make_terminal_event(
         command=command,
         stdout=completed.stdout or "",
@@ -336,6 +465,7 @@ def capture_command(home: Path, config: dict[str, Any], command: str, include_ex
     )
     created, event_path = store_event(home, event)
     state = "stored" if created else "deduped"
+    append_history(home, event, state)
     print(f"ai-memory: {state} terminal hash {event['event_hash'][:12]} at {event_path}")
 
     try:
@@ -408,7 +538,7 @@ def command_init(args: argparse.Namespace) -> int:
         print(f"Initialized project: {project.get('id', payload['project'])}")
     except Exception as exc:
         print(f"Project config saved locally. Server init will need retry: {exc}", file=sys.stderr)
-    print("Start terminal capture with: ai-memory watch")
+    print("Start terminal capture with: python -m ai_memory_cli watch")
     return 0
 
 
@@ -484,7 +614,7 @@ def command_chat_connect(args: argparse.Namespace) -> int:
 def command_run(args: argparse.Namespace) -> int:
     command = command_line(args.command)
     if not command:
-        raise SystemExit("Pass a command after --, for example: ai-memory run -- python --version")
+        raise SystemExit("Pass a command after --, for example: python -m ai_memory_cli run -- python --version")
     home = cli_home()
     config = load_config(home)
     return capture_command(home, config, command, args.include_excluded, "run")
@@ -502,6 +632,13 @@ def command_watch(args: argparse.Namespace) -> int:
             break
         if not command:
             continue
+        cleaned_command = clean_watch_command(command)
+        if cleaned_command != command:
+            if not cleaned_command:
+                print("ai-memory: skipped pasted prompt without a command.")
+                continue
+            print(f"ai-memory: using command without pasted prompt: {cleaned_command}")
+            command = cleaned_command
         if command.lower() in {"exit", "quit"}:
             break
         capture_command(home, config, command, args.include_excluded, "watch")
@@ -557,6 +694,224 @@ def command_sync(args: argparse.Namespace) -> int:
     return 0
 
 
+def command_agent_run(args: argparse.Namespace) -> int:
+    home = cli_home()
+    ensure_dirs(home)
+    interval = max(10, int(args.interval))
+    limit = max(1, int(args.limit))
+    state = {
+        "pid": os.getpid(),
+        "version": __version__,
+        "started_at": utc_now(),
+        "interval_seconds": interval,
+        "limit": limit,
+        "mode": "once" if args.once else "loop",
+    }
+    write_json(agent_state_path(home), state)
+    append_log(home, f"agent started pid={os.getpid()} interval={interval}s limit={limit}")
+
+    try:
+        while True:
+            config = load_config(home)
+            try:
+                synced = sync_events(home, config, limit=limit, quiet=True)
+                if synced:
+                    append_log(home, f"synced {synced} terminal event(s)")
+            except Exception as exc:
+                append_log(home, f"sync failed: {exc}")
+
+            if args.once:
+                break
+            time.sleep(interval)
+    finally:
+        state["stopped_at"] = utc_now()
+        write_json(agent_state_path(home), state)
+        append_log(home, "agent stopped")
+
+    return 0
+
+
+def command_agent_install(args: argparse.Namespace) -> int:
+    if os.name != "nt":
+        raise SystemExit("agent install currently supports Windows Task Scheduler only.")
+
+    home = cli_home()
+    config = load_config(home)
+    config["agent"] = {
+        "task_name": args.task_name,
+        "interval_seconds": args.interval,
+        "limit": args.limit,
+        "installed_at": utc_now(),
+    }
+    save_config(home, config)
+
+    if args.method in {"auto", "task"}:
+        python_executable = scheduler_python_executable(background=not args.console)
+        task_command = (
+            f'"{python_executable}" -m ai_memory_cli agent run '
+            f"--interval {int(args.interval)} --limit {int(args.limit)}"
+        )
+        result = subprocess.run(
+            [
+                "schtasks",
+                "/Create",
+                "/TN",
+                args.task_name,
+                "/SC",
+                "ONLOGON",
+                "/TR",
+                task_command,
+                "/F",
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        if result.returncode == 0:
+            append_log(home, f"installed Windows scheduled task: {args.task_name}")
+            print(f"Installed startup agent task: {args.task_name}")
+            print("It starts when you log in. Start it now with:")
+            print("python -m ai_memory_cli agent start")
+            return 0
+
+        if args.method == "task":
+            raise SystemExit((result.stderr or result.stdout).strip())
+
+        print("Task Scheduler install failed; falling back to user Startup folder.")
+        print((result.stderr or result.stdout).strip())
+
+    script_path = write_windows_startup_script(int(args.interval), int(args.limit))
+    append_log(home, f"installed Windows startup script: {script_path}")
+    print(f"Installed startup agent script: {script_path}")
+    print("It starts when you log in. Start it now with:")
+    print("python -m ai_memory_cli agent run")
+    return 0
+
+
+def command_agent_uninstall(args: argparse.Namespace) -> int:
+    if os.name != "nt":
+        raise SystemExit("agent uninstall currently supports Windows Task Scheduler only.")
+
+    removed = False
+    result = subprocess.run(
+        ["schtasks", "/Delete", "/TN", args.task_name, "/F"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode == 0:
+        removed = True
+
+    script_path = windows_startup_script_path()
+    if script_path.exists():
+        script_path.unlink()
+        removed = True
+
+    append_log(cli_home(), f"uninstalled Windows scheduled task: {args.task_name}")
+    if removed:
+        print("Removed startup agent registration.")
+    else:
+        print("No startup agent registration was found.")
+    return 0
+
+
+def command_agent_start(args: argparse.Namespace) -> int:
+    if os.name != "nt":
+        raise SystemExit("agent start currently supports Windows Task Scheduler only.")
+
+    home = cli_home()
+    config = load_config(home)
+    result = subprocess.run(
+        ["schtasks", "/Run", "/TN", args.task_name],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode == 0:
+        print(f"Started agent task: {args.task_name}")
+        return 0
+
+    agent_config = config.get("agent") if isinstance(config.get("agent"), dict) else {}
+    interval = int(agent_config.get("interval_seconds") or DEFAULT_AGENT_INTERVAL_SECONDS)
+    limit = int(agent_config.get("limit") or 50)
+    pid = start_detached_agent(interval, limit)
+    append_log(home, f"started detached agent pid={pid}")
+    print(f"Started detached agent process: pid={pid}")
+    return 0
+
+
+def command_agent_stop(args: argparse.Namespace) -> int:
+    if os.name != "nt":
+        raise SystemExit("agent stop currently supports Windows Task Scheduler only.")
+
+    home = cli_home()
+    result = subprocess.run(
+        ["schtasks", "/End", "/TN", args.task_name],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode == 0:
+        append_log(home, f"stopped Windows scheduled task: {args.task_name}")
+        print(f"Stopped agent task: {args.task_name}")
+        return 0
+
+    state = read_json(agent_state_path(home), {})
+    pid = state.get("pid")
+    if not pid:
+        print("No running detached agent pid was found.")
+        return 0
+
+    kill = subprocess.run(
+        ["taskkill", "/PID", str(pid), "/F"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if kill.returncode != 0:
+        raise SystemExit((kill.stderr or kill.stdout).strip())
+    append_log(home, f"stopped detached agent pid={pid}")
+    print(f"Stopped detached agent process: pid={pid}")
+    return 0
+
+
+def command_agent_status(args: argparse.Namespace) -> int:
+    home = cli_home()
+    config = load_config(home)
+    state = read_json(agent_state_path(home), {})
+    print(f"Storage: {home}")
+    print(f"API: {api_url(config)}")
+    print(f"Token: {'saved' if config.get('token') else 'missing'}")
+    if state:
+        print(f"Agent state: pid={state.get('pid', '-')} started={state.get('started_at', '-')}")
+    else:
+        print("Agent state: no local agent state file yet")
+
+    if os.name != "nt":
+        return 0
+
+    result = subprocess.run(
+        ["schtasks", "/Query", "/TN", args.task_name, "/FO", "LIST", "/V"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        print(f"Windows task: not installed ({args.task_name})")
+    else:
+        print(result.stdout.strip())
+
+    script_path = windows_startup_script_path()
+    print(f"Startup script: {'installed' if script_path.exists() else 'not installed'} ({script_path})")
+    return 0
+
+
 def command_status(_: argparse.Namespace) -> int:
     home = cli_home()
     config = load_config(home)
@@ -638,6 +993,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     watch = subparsers.add_parser("watch", help="Start a managed terminal that captures commands and output.")
     watch.add_argument("--include-excluded", action="store_true")
+    watch.add_argument("--version", action="version", version=f"ai-memory {__version__}")
     watch.set_defaults(func=command_watch)
 
     history = subparsers.add_parser("history", help="History import commands.")
@@ -652,6 +1008,39 @@ def build_parser() -> argparse.ArgumentParser:
     sync.add_argument("--limit", type=int, default=50)
     sync.set_defaults(func=command_sync)
 
+    agent = subparsers.add_parser("agent", help="Background sync agent commands.")
+    agent_subparsers = agent.add_subparsers(dest="agent_command", required=True)
+
+    agent_run = agent_subparsers.add_parser("run", help="Run the background sync loop.")
+    agent_run.add_argument("--interval", type=int, default=DEFAULT_AGENT_INTERVAL_SECONDS)
+    agent_run.add_argument("--limit", type=int, default=50)
+    agent_run.add_argument("--once", action="store_true")
+    agent_run.set_defaults(func=command_agent_run)
+
+    agent_install = agent_subparsers.add_parser("install", help="Install Windows startup task for the sync agent.")
+    agent_install.add_argument("--interval", type=int, default=DEFAULT_AGENT_INTERVAL_SECONDS)
+    agent_install.add_argument("--limit", type=int, default=50)
+    agent_install.add_argument("--task-name", default=WINDOWS_AGENT_TASK_NAME)
+    agent_install.add_argument("--method", choices=["auto", "task", "startup"], default="auto")
+    agent_install.add_argument("--console", action="store_true", help="Use python.exe instead of pythonw.exe for the scheduled task.")
+    agent_install.set_defaults(func=command_agent_install)
+
+    agent_uninstall = agent_subparsers.add_parser("uninstall", help="Remove Windows startup task for the sync agent.")
+    agent_uninstall.add_argument("--task-name", default=WINDOWS_AGENT_TASK_NAME)
+    agent_uninstall.set_defaults(func=command_agent_uninstall)
+
+    agent_start = agent_subparsers.add_parser("start", help="Start the installed Windows agent task now.")
+    agent_start.add_argument("--task-name", default=WINDOWS_AGENT_TASK_NAME)
+    agent_start.set_defaults(func=command_agent_start)
+
+    agent_stop = agent_subparsers.add_parser("stop", help="Stop the installed Windows agent task.")
+    agent_stop.add_argument("--task-name", default=WINDOWS_AGENT_TASK_NAME)
+    agent_stop.set_defaults(func=command_agent_stop)
+
+    agent_status = agent_subparsers.add_parser("status", help="Show background agent and Windows task state.")
+    agent_status.add_argument("--task-name", default=WINDOWS_AGENT_TASK_NAME)
+    agent_status.set_defaults(func=command_agent_status)
+
     status = subparsers.add_parser("status", help="Show local CLI state.")
     status.set_defaults(func=command_status)
 
@@ -669,3 +1058,15 @@ def main(argv: list[str] | None = None) -> int:
     except KeyboardInterrupt:
         print("Interrupted.", file=sys.stderr)
         return 130
+
+
+def watch_main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="watch", description="Start AI Memory terminal capture.")
+    parser.add_argument("--include-excluded", action="store_true")
+    parser.add_argument("--version", action="version", version=f"ai-memory {__version__}")
+    args = parser.parse_args(argv)
+    try:
+        return command_watch(args)
+    except KeyboardInterrupt:
+        print("Interrupted.", file=sys.stderr)
+        return 130

ai_memory_cli-0.1.5/src/ai_memory_cli.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: ai-memory-cli
+Version: 0.1.5
+Summary: Python CLI for AI Memory terminal capture and offline sync.
+Author: AI Memory
+License-Expression: MIT
+Keywords: ai,memory,cli,terminal,rag,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AI Memory CLI
+
+Standalone Python CLI for terminal capture, hashing, offline queueing, and sync to the temporary FastAPI backend.
+
+## Install
+
+For any user machine after the package is published:
+
+```powershell
+python -m pip install ai-memory-cli
+```
+
+Before PyPI publish, install from GitHub:
+
+```powershell
+python -m pip install "ai-memory-cli @ git+https://github.com/YOUR_ORG/ai-memory-cli.git"
+```
+
+For local development from this CLI repo:
+
+```powershell
+python -m pip install -e .
+```
+
+## Basic flow
+
+```powershell
+python -m ai_memory_cli auth --token TOKEN_FROM_WEBSITE --api-url https://api.your-domain.com
+python -m ai_memory_cli init --project my-project --repo owner/repo --workspace .
+python -m ai_memory_cli workspace connect --path . --repo owner/repo --editor vscode --package-manager pip
+watch
+```
+
+`watch` is a shortcut for `python -m ai_memory_cli watch`. If Windows Device Guard blocks the generated launcher, keep using `python -m ai_memory_cli watch`.
+On Windows the shortcut is installed as `watch.cmd`; the Python Scripts folder must be on `PATH` for bare `watch` to resolve.
+
+Use `python -m ai_memory_cli run -- COMMAND` when you only want to record one command.
+
+On Windows, `python -m ai_memory_cli ...` is the safest form because it avoids PATH issues and Device Guard policies that can block pip's generated `ai-memory.exe` launcher. Also avoid angle bracket placeholders in CMD because they are treated as file redirection.
+
+Inside `watch`, type the real command you want to capture, for example `python --version`. Do not type `python -m ai_memory_cli run -- ...` inside `watch`, or you will capture the nested CLI command too.
+
+## Background agent
+
+The background agent starts at Windows logon and keeps syncing queued terminal hashes whenever the API is reachable:
+
+```powershell
+python -m ai_memory_cli agent install
+python -m ai_memory_cli agent start
+python -m ai_memory_cli agent status
+```
+
+The agent does not secretly capture every terminal on the computer. Commands are captured when they run through:
+
+```powershell
+python -m ai_memory_cli watch
+python -m ai_memory_cli run -- python --version
+```
+
+To remove the startup task:
+
+```powershell
+python -m ai_memory_cli agent stop
+python -m ai_memory_cli agent uninstall
+```
+
+Agent logs are written to `%USERPROFILE%\.ai-memory-cli\logs\agent.log`.
+
+## Storage
+
+The CLI stores config and unsynced events in a separate folder:
+
+- Windows: `%USERPROFILE%\.ai-memory-cli`
+- macOS/Linux: `~/.ai-memory-cli`
+
+Set `AI_MEMORY_CLI_HOME` to override this location.
+
+Accepted command observations are also written as plain daily hash logs:
+
+- Windows: `%USERPROFILE%\.ai-memory-cli\history\YYYY-MM-DD.log`
+- macOS/Linux: `~/.ai-memory-cli/history/YYYY-MM-DD.log`
+
+These files include time/date, event hash, command hash, output hash, source, exit code, and working-folder name. They do not store raw command text or raw output.
+
+If a command is clearly invalid, such as a pasted prompt (`ai-memory> python --version`) or a shell "not recognized" error, the CLI skips storing it as an event.
+
+## Privacy and dedupe
+
+The CLI does not send raw commands or raw output to the backend. It sends:
+
+- `command_hash`
+- `output_hash`
+- `event_hash`
+- timestamps, exit code, shell, project, repo, and local metadata
+
+If the same command produces the same output again, the CLI keeps one event hash and increments `duplicate_count`.
+
+## Excluded commands
+
+Long-running development commands are not captured by default. They still run, but no hash event is stored.
+
+Default excluded patterns include:
+
+- `npm run ...`
+- `next dev`
+- `vite`
+- `uvicorn --reload`
+- `python -m uvicorn ... --reload`
+
+Use `--include-excluded` on `run` or `watch` if you need to capture them anyway.
+
+## Publish
+
+After this folder is pushed as its own public GitHub repo, publish to PyPI with:
+
+```powershell
+.\scripts\publish.ps1 -Repository pypi
+```

{ai_memory_cli-0.1.0 → ai_memory_cli-0.1.5}/src/ai_memory_cli.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 README.md
 pyproject.toml
+bin/watch.cmd
 src/ai_memory_cli/__init__.py
 src/ai_memory_cli/__main__.py
 src/ai_memory_cli/cli.py

ai_memory_cli-0.1.0/PKG-INFO

@@ -1,98 +0,0 @@
-Metadata-Version: 2.4
-Name: ai-memory-cli
-Version: 0.1.0
-Summary: Python CLI for AI Memory terminal capture and offline sync.
-Author: AI Memory
-License-Expression: MIT
-Keywords: ai,memory,cli,terminal,rag,developer-tools
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development
-Classifier: Topic :: Terminals
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# AI Memory CLI
-
-Standalone Python CLI for terminal capture, hashing, offline queueing, and sync to the temporary FastAPI backend.
-
-## Install
-
-For any user machine after the package is published:
-
-```powershell
-python -m pip install ai-memory-cli
-```
-
-Before PyPI publish, install from GitHub:
-
-```powershell
-python -m pip install "ai-memory-cli @ git+https://github.com/YOUR_ORG/ai-memory-cli.git"
-```
-
-For local development from this CLI repo:
-
-```powershell
-python -m pip install -e .
-```
-
-## Basic flow
-
-```powershell
-ai-memory auth --token <app-issued-cli-token> --api-url https://api.your-domain.com
-ai-memory init --project my-project --repo owner/repo --workspace .
-ai-memory workspace connect --path . --repo owner/repo --editor vscode --package-manager pip
-ai-memory watch
-```
-
-Use `ai-memory run -- <command>` when you only want to record one command.
-
-## Storage
-
-The CLI stores config and unsynced events in a separate folder:
-
-- Windows: `%USERPROFILE%\.ai-memory-cli`
-- macOS/Linux: `~/.ai-memory-cli`
-
-Set `AI_MEMORY_CLI_HOME` to override this location.
-
-## Privacy and dedupe
-
-The CLI does not send raw commands or raw output to the backend. It sends:
-
-- `command_hash`
-- `output_hash`
-- `event_hash`
-- timestamps, exit code, shell, project, repo, and local metadata
-
-If the same command produces the same output again, the CLI keeps one event hash and increments `duplicate_count`.
-
-## Excluded commands
-
-Long-running development commands are not captured by default. They still run, but no hash event is stored.
-
-Default excluded patterns include:
-
-- `npm run ...`
-- `next dev`
-- `vite`
-- `uvicorn --reload`
-- `python -m uvicorn ... --reload`
-
-Use `--include-excluded` on `run` or `watch` if you need to capture them anyway.
-
-## Publish
-
-After this folder is pushed as its own public GitHub repo, publish to PyPI with:
-
-```powershell
-.\scripts\publish.ps1 -Repository pypi
-```

ai_memory_cli-0.1.0/README.md

@@ -1,76 +0,0 @@
-# AI Memory CLI
-
-Standalone Python CLI for terminal capture, hashing, offline queueing, and sync to the temporary FastAPI backend.
-
-## Install
-
-For any user machine after the package is published:
-
-```powershell
-python -m pip install ai-memory-cli
-```
-
-Before PyPI publish, install from GitHub:
-
-```powershell
-python -m pip install "ai-memory-cli @ git+https://github.com/YOUR_ORG/ai-memory-cli.git"
-```
-
-For local development from this CLI repo:
-
-```powershell
-python -m pip install -e .
-```
-
-## Basic flow
-
-```powershell
-ai-memory auth --token <app-issued-cli-token> --api-url https://api.your-domain.com
-ai-memory init --project my-project --repo owner/repo --workspace .
-ai-memory workspace connect --path . --repo owner/repo --editor vscode --package-manager pip
-ai-memory watch
-```
-
-Use `ai-memory run -- <command>` when you only want to record one command.
-
-## Storage
-
-The CLI stores config and unsynced events in a separate folder:
-
-- Windows: `%USERPROFILE%\.ai-memory-cli`
-- macOS/Linux: `~/.ai-memory-cli`
-
-Set `AI_MEMORY_CLI_HOME` to override this location.
-
-## Privacy and dedupe
-
-The CLI does not send raw commands or raw output to the backend. It sends:
-
-- `command_hash`
-- `output_hash`
-- `event_hash`
-- timestamps, exit code, shell, project, repo, and local metadata
-
-If the same command produces the same output again, the CLI keeps one event hash and increments `duplicate_count`.
-
-## Excluded commands
-
-Long-running development commands are not captured by default. They still run, but no hash event is stored.
-
-Default excluded patterns include:
-
-- `npm run ...`
-- `next dev`
-- `vite`
-- `uvicorn --reload`
-- `python -m uvicorn ... --reload`
-
-Use `--include-excluded` on `run` or `watch` if you need to capture them anyway.
-
-## Publish
-
-After this folder is pushed as its own public GitHub repo, publish to PyPI with:
-
-```powershell
-.\scripts\publish.ps1 -Repository pypi
-```

ai_memory_cli-0.1.0/src/ai_memory_cli.egg-info/PKG-INFO

@@ -1,98 +0,0 @@
-Metadata-Version: 2.4
-Name: ai-memory-cli
-Version: 0.1.0
-Summary: Python CLI for AI Memory terminal capture and offline sync.
-Author: AI Memory
-License-Expression: MIT
-Keywords: ai,memory,cli,terminal,rag,developer-tools
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development
-Classifier: Topic :: Terminals
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# AI Memory CLI
-
-Standalone Python CLI for terminal capture, hashing, offline queueing, and sync to the temporary FastAPI backend.
-
-## Install
-
-For any user machine after the package is published:
-
-```powershell
-python -m pip install ai-memory-cli
-```
-
-Before PyPI publish, install from GitHub:
-
-```powershell
-python -m pip install "ai-memory-cli @ git+https://github.com/YOUR_ORG/ai-memory-cli.git"
-```
-
-For local development from this CLI repo:
-
-```powershell
-python -m pip install -e .
-```
-
-## Basic flow
-
-```powershell
-ai-memory auth --token <app-issued-cli-token> --api-url https://api.your-domain.com
-ai-memory init --project my-project --repo owner/repo --workspace .
-ai-memory workspace connect --path . --repo owner/repo --editor vscode --package-manager pip
-ai-memory watch
-```
-
-Use `ai-memory run -- <command>` when you only want to record one command.
-
-## Storage
-
-The CLI stores config and unsynced events in a separate folder:
-
-- Windows: `%USERPROFILE%\.ai-memory-cli`
-- macOS/Linux: `~/.ai-memory-cli`
-
-Set `AI_MEMORY_CLI_HOME` to override this location.
-
-## Privacy and dedupe
-
-The CLI does not send raw commands or raw output to the backend. It sends:
-
-- `command_hash`
-- `output_hash`
-- `event_hash`
-- timestamps, exit code, shell, project, repo, and local metadata
-
-If the same command produces the same output again, the CLI keeps one event hash and increments `duplicate_count`.
-
-## Excluded commands
-
-Long-running development commands are not captured by default. They still run, but no hash event is stored.
-
-Default excluded patterns include:
-
-- `npm run ...`
-- `next dev`
-- `vite`
-- `uvicorn --reload`
-- `python -m uvicorn ... --reload`
-
-Use `--include-excluded` on `run` or `watch` if you need to capture them anyway.
-
-## Publish
-
-After this folder is pushed as its own public GitHub repo, publish to PyPI with:
-
-```powershell
-.\scripts\publish.ps1 -Repository pypi
-```