auto-memory 0.1.0__py3-none-any.whl

auto_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: auto-memory
+Version: 0.1.0
+Summary: Your AI coding agent never forgets — progressive session recall for GitHub Copilot CLI
+Author-email: Desi Villanueva <217994822+dezgit2025@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dezgit2025/auto-memory
+Project-URL: Repository, https://github.com/dezgit2025/auto-memory
+Project-URL: Issues, https://github.com/dezgit2025/auto-memory/issues
+Keywords: session,recall,context,memory,cli,copilot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# auto-memory
+
+## Your AI coding agent has amnesia. Here's the fix.
+
+*~1,900 lines of Python. Zero dependencies. Saves you an hour a day.*
+
+> Built by [Desi Villanueva](https://github.com/dezgit2025)
+
+[![CI](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml/badge.svg)](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](pyproject.toml)
+[![Tests](https://img.shields.io/badge/tests-90%20passed-brightgreen)]()
+
+**Zero-dependency CLI that turns Copilot CLI's local SQLite into instant recall — no MCP server, no hooks, read-only, schema-checked. ~50 tokens per prompt.**
+
+**Works with:** GitHub Copilot CLI  
+**Coming soon:** Claude Code · Cursor · Codex 
+
+---
+
+### Quickstart
+
+```bash
+git clone https://github.com/dezgit2025/auto-memory.git
+cd auto-memory && ./install.sh
+session-recall health          # verify it works
+```
+
+Point your agent at [`deploy/install.md`](deploy/install.md) and let it cook. 🍳
+
+---
+
+## The Problem
+
+Every AI coding agent ships with a big number on the box. 200K tokens. Sounds massive. Here's what actually happens:
+
+```
+200,000  tokens — context window (theoretical max)
+120,000  tokens — effective limit before context rot kicks in (~60%)
+ -65,000  tokens — MCP tools
+ -25,000  tokens — instruction files
+=========
+ ~30,000  tokens — what you ACTUALLY have before quality degrades
+```
+
+LLMs don't degrade gracefully — once you cross roughly **60% of the context window**, the model starts losing coherence. The industry calls it "lost in the middle": attention goes to the beginning (instructions) and the end (recent turns), but your actual working context in the middle gets progressively fuzzier.
+
+I timed it over a week: **68 minutes per day** lost to re-orientation after compactions and new sessions.
+
+> It's a **death spiral of diminishing context** — each compaction leaves the agent slightly dumber, which burns more tokens explaining things, which triggers the next compaction sooner.
+
+### The Compaction Tax
+
+Every 20–30 turns, the context warning hits and you get two bad choices: ignore it and watch the agent hallucinate, or run `/compact` and watch it lobotomize itself into a tidy two-paragraph summary of a 30-minute investigation. Either way you lose five minutes re-narrating your own project back to the agent like it's a new hire. That's not a workflow — that's a hamster wheel.
+
+## The 200x ROI
+
+Here's the cost comparison that made me build this:
+
+| Operation | Tokens | What you get |
+|-----------|--------|-------------|
+| `grep -r "auth" src/` | ~5,000-10,000 | 500 results, mostly irrelevant |
+| `find . -name "*.py"` | ~2,000 | Every Python file, no context |
+| Agent re-orientation | ~2,000 | You re-explaining yesterday |
+| **`auto-memory files --json --limit 10`** | **~50** | **Exactly the 10 files you touched yesterday** |
+
+**50 tokens vs 10,000 — a 200x improvement.**
+
+## Before & After
+
+**Before auto-memory** — new session on a project:
+
+```
+You: Fix the failing test in the auth module
+
+Agent: Let me explore the project structure...
+       $ find . -name "*.py" | head -50           ← 2K tokens
+       $ grep -r "test.*auth" tests/              ← 5K tokens
+       $ cat tests/test_auth.py                    ← 3K tokens
+       $ cat src/auth/handler.py                   ← 2K tokens
+       I see several test files. Which test is failing?
+
+You: The one we were working on yesterday, the token refresh edge case
+
+Agent: Let me search for that...
+       $ grep -r "refresh" tests/                  ← 4K tokens
+       ...
+```
+
+Total: ~16K tokens burned, 8 minutes elapsed, agent still isn't oriented.
+
+**After auto-memory** — same scenario:
+
+```
+You: Fix the failing test in the auth module
+
+Agent: [auto-recall: auto-memory files --json --limit 10]
+       → src/auth/refresh.py, tests/test_refresh_edge_cases.py,
+         src/auth/token_store.py (last touched 14h ago)
+
+       [auto-recall: auto-memory list --json --limit 3]
+       → Yesterday: "Fixed token refresh race condition, one edge case
+         test still failing on expired token + network timeout combo"
+
+       I can see from your last session that test_refresh_edge_cases.py
+       has a failing test for the expired token + network timeout case.
+       Let me look at that specific test...
+       $ cat tests/test_refresh_edge_cases.py      ← 1K tokens (targeted)
+```
+
+Total: ~1.1K tokens, 30 seconds, agent is immediately productive.
+
+## How it compares
+
+| Approach | Dependencies | Writes to DB | Setup | Agent-native |
+|----------|-------------|-------------|-------|-------------|
+| **auto-memory** | None (stdlib) | ❌ Read-only | `pip install` | ✅ Instruction-file |
+| MCP server | Node.js runtime | Varies | Server config | ❌ Protocol layer |
+| Custom hooks | Varies | Often yes | Hook scripts | ❌ Event-driven |
+| Manual grep | None | ❌ | None | ❌ Manual |
+
+## Mental Model: RAM vs Disk
+
+- **Context window = RAM.** Fast, limited, clears on restart.
+- **session-store.db = Disk.** Persistent, searchable, grows forever.
+
+auto-memory is the **page fault handler** — it pulls exact facts from disk in ~50 tokens when the agent needs them.
+
+**It's not unlimited context. It's unlimited context *recall*.** In practice, same thing.
+
+## Design
+
+```
+┌─────────────────────────────────────────────────┐
+│  copilot-instructions.md                        │
+│  "Run auto-memory FIRST on every prompt"         │
+└──────────────────┬──────────────────────────────┘
+                   │ agent reads instruction
+                   ▼
+┌─────────────────────────────────────────────────┐
+│  auto-memory CLI                                │
+│  (pure Python, zero deps, read-only)            │
+└──────────────────┬──────────────────────────────┘
+                   │ SELECT ... FROM sessions
+                   ▼
+┌─────────────────────────────────────────────────┐
+│  ~/.copilot/session-store.db                    │
+│  (SQLite + FTS5, owned by Copilot CLI binary)   │
+└─────────────────────────────────────────────────┘
+```
+
+- **Zero dependencies** — stdlib only (sqlite3, json, argparse)
+- **Read-only** — never writes to `~/.copilot/session-store.db`
+- **WAL-safe** — exponential backoff retry on SQLITE_BUSY (50→150→450ms)
+- **Schema-aware** — validates expected schema on every call, fails fast on drift
+- **Telemetry** — ring buffer of last 100 invocations for concurrency monitoring
+
+## Usage
+
+### Try these prompts with your agent
+
+ Once wired into your agent's instruction file, session-recall runs on every prompt — giving the agent your recent files and sessions as context before it does anything else.
+
+
+```
+"Search recent sessions about fixing the db connection bug"
+"Check past 5 days sessions for latest plans?"
+"Pick up where we left off on the API refactor"
+"search recent sessions for last 10 files we modified"
+"search sessions for the db migration bug"
+```
+
+No special syntax. The agent reads your session history and gets oriented in seconds instead of minutes.
+
+### How it works under the hood
+
+Progressive disclosure — most prompts never get past Tier 1.
+
+**Tier 1 — Cheap scan (~50 tokens).** Usually enough.
+
+```bash
+session-recall files --json --limit 10
+session-recall list --json --limit 5
+```
+
+**Tier 2 — Focused recall (~200 tokens).** When Tier 1 isn't enough.
+
+```bash
+session-recall search "specific term" --json
+```
+
+**Tier 3 — Full session detail (~500 tokens).** Only when investigating something specific.
+
+```bash
+session-recall show <session-id> --json
+```
+
+**Operational commands:**
+
+```bash
+session-recall health          # 9-dimension health dashboard
+session-recall schema-check    # validate DB schema after Copilot CLI upgrades
+```
+
+## Health Check
+
+```
+Dim Name                   Zone     Score  Detail
+----------------------------------------------------------------------
+ 1  DB Freshness           🟢 GREEN   8.0  15.8h old
+ 2  Schema Integrity       🟢 GREEN  10.0  All tables/columns OK
+ 3  Query Latency          🟢 GREEN  10.0  1ms
+ 4  Corpus Size            🟢 GREEN  10.0  399 sessions
+ 5  Summary Coverage       🟢 GREEN   7.4  92% (367/399)
+ 6  Repo Coverage          🟢 GREEN  10.0  8 sessions for owner/repo
+ 7  Concurrency            🟢 GREEN  10.0  busy=0.0%, p95=48ms
+ 8  E2E Probe              🟢 GREEN  10.0  list→show OK
+ 9  Progressive Disclosure  ⚪ CALIBRATING  —  Collecting baseline (n=42/200)
+```
+
+## Agent Integration
+
+auto-memory works with **any agent that supports instruction files** — GitHub Copilot CLI, Claude Code, Cursor, Aider, Windsurf, and more. Installation wires session-recall into your agent's instruction file so it runs context recall automatically.
+
+See [`deploy/install.md`](deploy/install.md) for setup and [`copilot-instructions-template.md`](copilot-instructions-template.md) for integration patterns.
+
+See [`UPGRADE-COPILOT-CLI.md`](UPGRADE-COPILOT-CLI.md) for schema validation after Copilot CLI upgrades.
+
+## What This Isn't
+
+- **Not a vector database** — no embeddings, SQLite FTS5 only.
+- **Not cross-machine sync** — local only.
+- **Not a replacement for project documentation** — recalls *what you did*, not *how the system works*.
+
+## FAQ
+
+**Is it safe? Does it modify my session data?**
+No. auto-memory is strictly read-only. It never writes to `~/.copilot/session-store.db`.
+
+**What happens when Copilot CLI updates its schema?**
+Run `session-recall schema-check` to validate. The tool fails fast on schema drift rather than returning bad data. See [UPGRADE-COPILOT-CLI.md](UPGRADE-COPILOT-CLI.md).
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines. Issues, PRs, and docs improvements are welcome.
+
+⭐ **If auto-memory saved you time, [star the repo](https://github.com/dezgit2025/auto-memory)** — it's the best way to help others find it.
+
+🔗 **Share it:** *"Zero-dependency CLI that gives your AI coding agent session memory. Read-only, schema-checked, ~50 tokens per prompt."* → [github.com/dezgit2025/auto-memory](https://github.com/dezgit2025/auto-memory)
+
+## Disclaimer
+
+This is an independent open-source project. It is **not** affiliated with, endorsed by, or supported by Microsoft, GitHub, or any other company. There is no official support — use at your own risk. Contributions and issues are welcome on GitHub.
+
+## License
+
+MIT

auto_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+auto_memory-0.1.0.dist-info/licenses/LICENSE,sha256=xUWsqT_KBHFgGHazfzrn0HZF3m3cFmQohZb03j9XA5g,1081
+session_recall/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_recall/__main__.py,sha256=i_QWXoFOpQSWPh5SrHjZVYbpdf0BvkqwsjwLuXwGaYg,4633
+session_recall/config.py,sha256=QPYZsvpb1k_IH-U2Wa6tw0NIFj8UL9QVmpNHdenVPdY,440
+session_recall/types.py,sha256=AILEMG4TLt318KmKQcbjM7xZvpBncGMhksgn7TytBrQ,696
+session_recall/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_recall/commands/checkpoints.py,sha256=PSvSXRNgtjh-H5JkAfrlNYurWcKDo-cQarDs8CFgfZ8,1805
+session_recall/commands/files.py,sha256=CJJV2QTWCOMv0lzF4aLUPACFnU0M3dE1C4cbBpoLUb8,1724
+session_recall/commands/health.py,sha256=CHqKnbPGIuNboMedBU7yRc5zwczpEkXt-JWuZbWaLYw,1561
+session_recall/commands/list_sessions.py,sha256=ySkrZsu_XMruXUIn3KyOQ-Lw5V-5Ojq72V0vnk01-Fc,3261
+session_recall/commands/schema_check_cmd.py,sha256=u8wGqjlg27usWMsFH18aOMXtr-58U3lStZjiQSV6mFM,851
+session_recall/commands/search.py,sha256=TmRkXcP6ttWIB2jbSDmVm66GJSShu_bZwsCMr8Nonns,4306
+session_recall/commands/show_session.py,sha256=2wev-aV0OKeXXdOEgnuWvot9Q0A5uARen4XHQ2Ycv44,2839
+session_recall/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_recall/db/connect.py,sha256=XDBDLsajL16EaVOvsWB_KF9PDB7TPR8p728Sf2ChWNY,1232
+session_recall/db/schema_check.py,sha256=7NgDsf-sD0tYJAOh8Z1Qkw_S9--QgMAD_EvWDjhkDHE,1166
+session_recall/health/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_recall/health/dim_concurrency.py,sha256=t6_PxMRuseEXWOshUm_9vb7tlC8J-b_WdGl9c589edY,1560
+session_recall/health/dim_corpus.py,sha256=ef7036raknEdh3zjNAlUDQiQSre9vtlRVSULnp6S3gM,681
+session_recall/health/dim_disclosure.py,sha256=iIFg5P2oSAzh5IxogmvmBwmDvWErT2ZfDRGOOnZKXgY,6355
+session_recall/health/dim_e2e.py,sha256=EPTZOaIRlKit2SNuhHRV6veJAPj331KkMxkHQ2qI01Q,1177
+session_recall/health/dim_freshness.py,sha256=7nN93Myfo5CdZna3R2-VLJ0XPzkTJNfUHw_BNYKcfS8,698
+session_recall/health/dim_latency.py,sha256=Z6igJ4GR4F7nC-aC_oxxYn65zAc8NWGHVvMeiBVKuns,1067
+session_recall/health/dim_repo_coverage.py,sha256=SEv2_OPzbo61W4AEayu9BsLwviRohyaAgBTXYo5AbQY,1051
+session_recall/health/dim_schema.py,sha256=HLo5UGFW9IiEL37SjpNRAqykd9Lsb22VOe1q0wWlJMo,1029
+session_recall/health/dim_summary_coverage.py,sha256=-R2dO8EiXvUuXcB69GLh7y-EXrkhLJwRYbxqKjE5xT8,1453
+session_recall/health/scoring.py,sha256=i_Z5g5u3Vq_cNF5YxgUDBRVlQRBpGeZaonjA2oXKC5s,1657
+session_recall/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_recall/tests/test_connect.py,sha256=HJeJiGwxaegYM1mg3mcpJ04JUWqgaF72m_J4gSU5zco,1308
+session_recall/tests/test_days_filter.py,sha256=_hjs6y50jsJHszOuBW3tpyzQKabOUl3_4d7ZrcITxXw,9101
+session_recall/tests/test_dim_disclosure.py,sha256=UcK_e0zXMRvgCr4dvf2qbnRlb-XivHDBpzzNv2LdE5Q,3481
+session_recall/tests/test_health_scoring.py,sha256=JAhOgPT-Na677HcGvmxFYHWaemuVRiNzTaREx59B6f0,1865
+session_recall/tests/test_list_sessions.py,sha256=a2fx_KkFkToR3tsWwIimPTSTLAXct5MgPADxn_XOQOA,4383
+session_recall/tests/test_parser.py,sha256=F3Fq4w7D_rGMbOGtINi-mpscL5rnG-SJMXGJT1CDnvc,690
+session_recall/tests/test_sanitize_terminal.py,sha256=zLSKIA8GdEVWdsSBrsHGZwlq45rbv6K149Oy_jmE1Do,1474
+session_recall/tests/test_schema_check.py,sha256=o2BsEqamMyTjVLbRbVUjAqJW8ovox60Z0cm5ho1zUMI,2435
+session_recall/tests/test_search_sanitize.py,sha256=ceLP5ndVkF-3a-ACs0sZAgFYE4MJA6oG-SM2CZRsvRM,1746
+session_recall/tests/test_show_session.py,sha256=mysfTd_U5Rn97En756k1wgS7qjZK1gcD446y0NSm5r8,5886
+session_recall/tests/test_telemetry.py,sha256=5PoeVk8hyPmYNrOJnVcDjpv8dcTV2B3X9YJAXhKJWxM,2337
+session_recall/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_recall/util/detect_repo.py,sha256=bLOIsenTnhmygZr_zYYhJk3-VmsGwvu4gJgXIORJPHQ,777
+session_recall/util/format_output.py,sha256=zmcJq7v0nrRwDS7mixOPZjvLNdj5cEQzxVxTWeLLYQQ,1934
+session_recall/util/telemetry.py,sha256=GaNqmA4UJkmt30JAn0M1Sl6FK_HKhtfAZokGDFahzWw,2401
+auto_memory-0.1.0.dist-info/METADATA,sha256=KpqcNvxMwH5d-6GcfaDLP02PWxZ27OCdSm-aKNHYIZA,12263
+auto_memory-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+auto_memory-0.1.0.dist-info/entry_points.txt,sha256=BHVjZhFujSpgxlyRqqIu4V1jOdv_xKD-19zmKqQYPEE,64
+auto_memory-0.1.0.dist-info/top_level.txt,sha256=xKR1tZQmXXPwvC0rXmDS8tr9LZo_wZOIfMps2OqtFGo,15
+auto_memory-0.1.0.dist-info/RECORD,,

auto_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

auto_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+session-recall = session_recall.__main__:main

auto_memory-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 auto-memory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auto_memory-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+session_recall

session_recall/__main__.py

@@ -0,0 +1,117 @@
+"""auto-memory CLI — progressive session disclosure for Copilot CLI."""
+import argparse
+import sys
+import time
+
+from .config import TELEMETRY_PATH
+from .util import telemetry
+
+
+def _non_negative_int(v):
+    """Argparse type: non-negative integer."""
+    i = int(v)
+    if i < 0:
+        raise argparse.ArgumentTypeError(f"must be >= 0, got {v}")
+    return i
+
+
+TIER_MAP = {
+    "list": 1, "files": 1, "checkpoints": 1,   # Tier 1 — cheap scan
+    "search": 2,                                  # Tier 2 — focused search
+    "show": 3,                                    # Tier 3 — deep dive
+    "health": 0, "schema-check": 0,              # Tier 0 — meta/ops
+    "calibrate": 0,                               # Tier 0 — meta (Phase 4)
+}
+
+
+def main() -> None:
+    telemetry.init(TELEMETRY_PATH)
+    t0 = time.monotonic()
+    parser = argparse.ArgumentParser(prog="auto-memory", description="Query Copilot CLI session history")
+    sub = parser.add_subparsers(dest="command")
+
+    p_list = sub.add_parser("list", help="Recent sessions")
+    p_list.add_argument("--repo", default=None)
+    p_list.add_argument("--limit", type=int, default=None)
+    p_list.add_argument("--days", type=int, default=None, help="Only include sessions from last N days (default 30)")
+    p_list.add_argument("--json", action="store_true")
+
+    p_schema = sub.add_parser("schema-check", help="Validate DB schema")
+    p_schema.add_argument("--json", action="store_true")
+
+    p_files = sub.add_parser("files", help="Recently touched files")
+    p_files.add_argument("--json", action="store_true")
+    p_files.add_argument("--repo", default=None)
+    p_files.add_argument("--limit", type=int, default=None)
+    p_files.add_argument("--days", type=int, default=None, help="Only include files from last N days")
+
+    p_cp = sub.add_parser("checkpoints", help="Recent checkpoints")
+    p_cp.add_argument("--json", action="store_true")
+    p_cp.add_argument("--repo", default=None)
+    p_cp.add_argument("--limit", type=int, default=None)
+    p_cp.add_argument("--days", type=int, default=None, help="Only include checkpoints from last N days")
+
+    p_show = sub.add_parser("show", help="Show session details")
+    p_show.add_argument("session_id")
+    p_show.add_argument("--json", action="store_true")
+    p_show.add_argument("--turns", type=_non_negative_int, default=None)
+    p_show.add_argument("--full", action="store_true")
+
+    p_search = sub.add_parser("search", help="Full-text search")
+    p_search.add_argument("query")
+    p_search.add_argument("--json", action="store_true")
+    p_search.add_argument("--repo", default=None)
+    p_search.add_argument("--limit", type=int, default=None)
+    p_search.add_argument("--days", type=int, default=None, help="Only include sessions from last N days")
+
+    p_health = sub.add_parser("health", help="Health check (9 dimensions)")
+    p_health.add_argument("--json", action="store_true")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    exit_code = 1
+    if args.command == "list":
+        from .commands.list_sessions import run
+        exit_code = run(args)
+    elif args.command == "schema-check":
+        from .commands.schema_check_cmd import run
+        exit_code = run(args)
+    elif args.command == "files":
+        from .commands.files import run
+        exit_code = run(args)
+    elif args.command == "checkpoints":
+        from .commands.checkpoints import run
+        exit_code = run(args)
+    elif args.command == "show":
+        from .commands.show_session import run
+        exit_code = run(args)
+    elif args.command == "search":
+        from .commands.search import run
+        exit_code = run(args)
+    elif args.command == "health":
+        from .commands.health import run
+        exit_code = run(args)
+    else:
+        print(f"'{args.command}' not yet implemented. Coming in Phase 2.", file=sys.stderr)
+
+    duration_ms = int((time.monotonic() - t0) * 1000)
+    tier = TIER_MAP.get(args.command)  # None if command unknown
+    qhash = None
+    sid_prefix = None
+    wtier = None  # Phase 4 will populate this
+    if args.command == "search":
+        qhash = telemetry.query_hash(getattr(args, "query", "") or "")
+    elif args.command == "show":
+        sid = getattr(args, "session_id", "") or ""
+        sid_prefix = sid[:8] if sid else None
+    telemetry.record(cmd=args.command, duration_ms=duration_ms, exit_code=exit_code,
+                     tier=tier, query_hash=qhash, session_id_prefix=sid_prefix,
+                     window_tier=wtier)
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

session_recall/commands/checkpoints.py

@@ -0,0 +1,42 @@
+"""List recent checkpoints with session context."""
+import sys
+from ..db.connect import connect_ro
+from ..db.schema_check import schema_check
+from ..config import DB_PATH
+from ..util.detect_repo import detect_repo
+from ..util.format_output import output
+
+_BASE = """SELECT c.checkpoint_number, c.title, c.overview, c.created_at,
+           c.session_id, s.summary as session_summary FROM checkpoints c
+           JOIN sessions s ON s.id = c.session_id"""
+
+
+def run(args) -> int:
+    conn = connect_ro(DB_PATH)
+    problems = schema_check(conn)
+    if problems:
+        for p in problems:
+            print(f"   - {p}", file=sys.stderr)
+        conn.close()
+        return 2
+    repo = getattr(args, 'repo', None) or detect_repo()
+    limit = getattr(args, 'limit', None) or 5
+    days = getattr(args, 'days', None)
+    date_filter = " AND c.created_at >= datetime('now', ?)" if days else ""
+    date_param = (f"-{days} days",) if days else ()
+    if repo and repo != "all":
+        sql = _BASE + f" WHERE s.repository = ?{date_filter} ORDER BY c.created_at DESC LIMIT ?"
+        rows = conn.execute(sql, (repo, *date_param, limit)).fetchall()
+    else:
+        where = f" WHERE 1=1{date_filter}" if days else ""
+        sql = _BASE + where + " ORDER BY c.created_at DESC LIMIT ?"
+        rows = conn.execute(sql, (*date_param, limit)).fetchall()
+    checkpoints = [{
+        "checkpoint_number": r["checkpoint_number"], "title": r["title"],
+        "overview": (r["overview"] or "")[:300], "date": (r["created_at"] or "")[:10],
+        "session_id": r["session_id"][:8], "session_summary": r["session_summary"],
+    } for r in rows]
+    output({"repo": repo or "all", "count": len(checkpoints), "checkpoints": checkpoints},
+           json_mode=getattr(args, 'json', False))
+    conn.close()
+    return 0

session_recall/commands/files.py

@@ -0,0 +1,42 @@
+"""List recently touched files with session attribution."""
+import sys
+from ..db.connect import connect_ro
+from ..db.schema_check import schema_check
+from ..config import DB_PATH
+from ..util.detect_repo import detect_repo
+from ..util.format_output import output
+
+_BASE = """SELECT sf.file_path, sf.tool_name, sf.first_seen_at,
+           sf.session_id, s.summary FROM session_files sf
+           JOIN sessions s ON s.id = sf.session_id"""
+
+
+def run(args) -> int:
+    conn = connect_ro(DB_PATH)
+    problems = schema_check(conn)
+    if problems:
+        for p in problems:
+            print(f"   - {p}", file=sys.stderr)
+        conn.close()
+        return 2
+    repo = getattr(args, 'repo', None) or detect_repo()
+    limit = getattr(args, 'limit', None) or 10
+    days = getattr(args, 'days', None)
+    date_filter = " AND sf.first_seen_at >= datetime('now', ?)" if days else ""
+    date_param = (f"-{days} days",) if days else ()
+    if repo and repo != "all":
+        sql = _BASE + f" WHERE s.repository = ?{date_filter} ORDER BY sf.first_seen_at DESC LIMIT ?"
+        rows = conn.execute(sql, (repo, *date_param, limit)).fetchall()
+    else:
+        where = f" WHERE 1=1{date_filter}" if days else ""
+        sql = _BASE + where + " ORDER BY sf.first_seen_at DESC LIMIT ?"
+        rows = conn.execute(sql, (*date_param, limit)).fetchall()
+    files = [{
+        "file_path": r["file_path"], "tool_name": r["tool_name"],
+        "date": (r["first_seen_at"] or "")[:10],
+        "session_id": r["session_id"][:8], "session_summary": r["summary"],
+    } for r in rows]
+    output({"repo": repo or "all", "count": len(files), "files": files},
+           json_mode=getattr(args, 'json', False))
+    conn.close()
+    return 0

session_recall/commands/health.py

@@ -0,0 +1,38 @@
+"""Health check orchestrator — run all 9 dimensions and report."""
+import sys
+from ..health.scoring import overall_score
+from ..health import (dim_freshness, dim_schema, dim_latency, dim_corpus,
+                      dim_summary_coverage, dim_repo_coverage, dim_concurrency,
+                      dim_e2e, dim_disclosure)
+from ..util.format_output import fmt_json
+
+DIMS = [dim_freshness, dim_schema, dim_latency, dim_corpus,
+        dim_summary_coverage, dim_repo_coverage, dim_concurrency, dim_e2e,
+        dim_disclosure]
+
+ZONE_ICON = {"GREEN": "🟢", "AMBER": "🟡", "RED": "🔴"}
+ZONE_ICON["CALIBRATING"] = "⚪"
+
+
+def run(args) -> int:
+    results = [d.check() for d in DIMS]
+    score = overall_score(results)
+    hints = [r["hint"] for r in results if r["zone"] != "GREEN" and r.get("hint")]
+
+    if getattr(args, "json", False):
+        print(fmt_json({"overall_score": score, "dims": results, "top_hints": hints[:3]}))
+    else:
+        print(f"\n{'Dim':<3s} {'Name':<22s} {'Zone':<8s} {'Score':>5s}  Detail")
+        print("-" * 70)
+        for i, r in enumerate(results, 1):
+            icon = ZONE_ICON.get(r["zone"], "?")
+            score_str = f"{r['score']:5.1f}" if r.get("score") is not None else "  -  "
+            print(f" {i:<2d} {r['name']:<22s} {icon} {r['zone']:<5s} {score_str}  {r['detail']}")
+        print("-" * 70)
+        print(f"    {'Overall':<22s}        {score:5.1f}")
+        if hints:
+            print(f"\n💡 Hints:")
+            for h in hints[:3]:
+                print(f"   • {h}")
+        print()
+    return 0