memor-cli 0.1.1__tar.gz → 0.3.0__tar.gz

{memor_cli-0.1.1/memor_cli.egg-info → memor_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memor-cli
-Version: 0.1.1
+Version: 0.3.0
 Summary: Measured memory for coding agents. Fire and forget — no API keys needed.
 Author-email: Nimit Bhandari <nimitbhandari17@gmail.com>
 License-Expression: MIT
@@ -46,7 +46,7 @@ Dynamic: license-file
 ```
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-153%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-179%20passing-brightgreen.svg)]()
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memor-cli.svg)](https://pypi.org/project/memor-cli/)
 
@@ -65,7 +65,10 @@ pipx install memor-cli
 # Install the Claude Code hook + download embedding model (~60MB)
 memor install-hook
 
-# Start the background daemon
+# Start as a background service (macOS/Linux)
+memor service install
+
+# Or run in the foreground
 memor daemon
 ```
 
@@ -92,7 +95,13 @@ memor dashboard
   Embed query locally (model2vec, ~2ms)
       |
       v
-  Hybrid scoring: similarity + recency + kind weight + quality
+  Hybrid retrieval: dense vectors + lexical BM25, fused (RRF)
+      |
+      v
+  Relevance gate drops off-topic matches (inject nothing if nothing fits)
+      |
+      v
+  Rank: similarity + recency + kind weight + quality
       |
       v
   Inject relevant context into prompt
@@ -104,20 +113,31 @@ memor dashboard
 
 **Two background processes:**
 
-1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates. All local.
+1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates, tracks session-level token usage. All local.
 2. **Hook** — fires on every prompt, recalls relevant memories, injects them as context. Sub-15ms.
 
 **No API keys required.** Embeddings run locally via [model2vec](https://github.com/MinishLab/model2vec) (potion-base-8M, 256-dim). Vectors stored in [sqlite-vec](https://github.com/asg017/sqlite-vec). Everything runs on your machine.
 
 ---
 
-## Hybrid Scoring
+## Hybrid Retrieval
+
+Memor retrieves over two channels and fuses them, so it catches both semantic matches and exact terms:
+
+- **Dense** — local vector similarity (model2vec) for semantic recall.
+- **Lexical** — SQLite FTS5 / BM25 over the raw text, to recover exact identifiers, error strings, and API names that static embeddings blur together.
+
+The two rankings are combined with **Reciprocal Rank Fusion (RRF)**. A **relevance gate** drops anti-correlated (off-topic) candidates *before* ranking, so an unrelated prompt injects nothing rather than the least-bad guess. The lexical channel only activates when the dense channel finds the query on-topic, preventing generic words from pulling in noise.
+
+> Tunable via `MEMOR_MIN_SIMILARITY` (relevance floor, default 0.0) and `MEMOR_MAX_TOKENS` (injection budget, default 1500).
+
+## Scoring
 
-Memor doesn't just match keywords. Each memory is scored by four signals:
+Surviving candidates are ranked by four signals:
 
 | Signal | Weight | How it works |
 |---|---|---|
-| **Semantic similarity** | 50% | Vector cosine distance between query and memory |
+| **Semantic similarity** | 50% | Dense + lexical relevance, fused via RRF |
 | **Recency** | 25% | Exponential decay with 14-day half-life — recent decisions rank higher |
 | **Kind weight** | 15% | Distilled memories (1.3x) rank above raw session chunks (1.0x) |
 | **Quality** | 10% | Bayesian score from implicit feedback — memories the agent actually uses rank higher |
@@ -147,10 +167,11 @@ Memories are automatically classified as `decision`, `bugfix`, `lesson`, `snippe
 memor dashboard
 ```
 
-Shows:
-- **Memory bank** — session chunks, distilled memories, projects tracked
-- **Context efficiency** — overhead %, recall precision, quality scores per session
-- **Per-project breakdown** — which projects have the most context
+Dark fintech-inspired UI showing:
+- **Hero metrics** — total memories, recall count, avg latency, coverage — with sparkline bars
+- **Daily recall activity** — stacked bar chart of hits vs misses over time
+- **Session efficiency** — real token savings measured from API usage data (avg tokens/turn with vs without recall)
+- **Per-project breakdown** — artifact counts, token totals, last activity
 - **Recent recalls** — every hook event with scores, latency, and status
 
 ---
@@ -162,6 +183,11 @@ memor help                           Print the full manual
 memor install-hook                   Install Claude Code hook + download model
 memor daemon                         Auto-ingest + distill (background watcher)
 memor dashboard                      Web dashboard on localhost:8420
+memor version                        Print installed version
+memor service install                Run daemon as background service (launchd/systemd)
+memor service stop                   Stop the background service
+memor service uninstall              Remove the background service
+memor service status                 Check if the service is running
 memor query <text>                   Search memories from the CLI
 memor reingest                       Wipe DB and re-ingest everything
 memor reingest --project <name>      Re-ingest only one project
@@ -193,16 +219,17 @@ memor/
 +-- feedback.py           Implicit feedback analyzer (usage detection)
 |
 +-- retrieve/
-|   +-- retriever.py      Hybrid scoring: similarity + recency + kind + quality
+|   +-- retriever.py      Hybrid retrieval (dense + BM25, RRF) + relevance gate + scoring
 |
 +-- store/
-|   +-- sqlite_store.py   SQLite + sqlite-vec (WAL mode, dimension safety)
+|   +-- sqlite_store.py   SQLite + sqlite-vec + FTS5 (WAL mode, dimension safety)
 |
 +-- embed/
 |   +-- local.py          model2vec (potion-base-8M, 256-dim, ~60MB)
 |   +-- api.py            OpenAI-compatible embedding API (optional)
 |   +-- fake.py           Deterministic SHA-256 embedder (tests)
 |
++-- service.py            Background service management (launchd/systemd)
 +-- dashboard/
 |   +-- server.py         FastAPI dashboard backend
 |   +-- static/index.html Self-contained dashboard (no CDN deps)
@@ -227,7 +254,7 @@ skill/recall.py            Standalone recall script
 **Nothing leaves your machine.** In the default configuration:
 
 - **No telemetry, no analytics, no phone-home.** Zero outbound network calls.
-- **Embeddings run locally** via model2vec ONNX (one-time model download from HuggingFace — no user data sent).
+- **Embeddings run locally** via model2vec static token embeddings — no inference runtime, no GPU (one-time model download from HuggingFace — no user data sent).
 - **Hook transport is a Unix socket** (`~/.memor/hook.sock`), not a network port.
 - **Dashboard binds localhost only.**
 
@@ -263,7 +290,7 @@ cd memor-ai
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest  # 153 tests
+pytest  # 179 tests
 ```
 
 ---

{memor_cli-0.1.1 → memor_cli-0.3.0}/README.md

@@ -9,7 +9,7 @@
 ```
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-153%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-179%20passing-brightgreen.svg)]()
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memor-cli.svg)](https://pypi.org/project/memor-cli/)
 
@@ -28,7 +28,10 @@ pipx install memor-cli
 # Install the Claude Code hook + download embedding model (~60MB)
 memor install-hook
 
-# Start the background daemon
+# Start as a background service (macOS/Linux)
+memor service install
+
+# Or run in the foreground
 memor daemon
 ```
 
@@ -55,7 +58,13 @@ memor dashboard
   Embed query locally (model2vec, ~2ms)
       |
       v
-  Hybrid scoring: similarity + recency + kind weight + quality
+  Hybrid retrieval: dense vectors + lexical BM25, fused (RRF)
+      |
+      v
+  Relevance gate drops off-topic matches (inject nothing if nothing fits)
+      |
+      v
+  Rank: similarity + recency + kind weight + quality
       |
       v
   Inject relevant context into prompt
@@ -67,20 +76,31 @@ memor dashboard
 
 **Two background processes:**
 
-1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates. All local.
+1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates, tracks session-level token usage. All local.
 2. **Hook** — fires on every prompt, recalls relevant memories, injects them as context. Sub-15ms.
 
 **No API keys required.** Embeddings run locally via [model2vec](https://github.com/MinishLab/model2vec) (potion-base-8M, 256-dim). Vectors stored in [sqlite-vec](https://github.com/asg017/sqlite-vec). Everything runs on your machine.
 
 ---
 
-## Hybrid Scoring
+## Hybrid Retrieval
+
+Memor retrieves over two channels and fuses them, so it catches both semantic matches and exact terms:
+
+- **Dense** — local vector similarity (model2vec) for semantic recall.
+- **Lexical** — SQLite FTS5 / BM25 over the raw text, to recover exact identifiers, error strings, and API names that static embeddings blur together.
+
+The two rankings are combined with **Reciprocal Rank Fusion (RRF)**. A **relevance gate** drops anti-correlated (off-topic) candidates *before* ranking, so an unrelated prompt injects nothing rather than the least-bad guess. The lexical channel only activates when the dense channel finds the query on-topic, preventing generic words from pulling in noise.
+
+> Tunable via `MEMOR_MIN_SIMILARITY` (relevance floor, default 0.0) and `MEMOR_MAX_TOKENS` (injection budget, default 1500).
+
+## Scoring
 
-Memor doesn't just match keywords. Each memory is scored by four signals:
+Surviving candidates are ranked by four signals:
 
 | Signal | Weight | How it works |
 |---|---|---|
-| **Semantic similarity** | 50% | Vector cosine distance between query and memory |
+| **Semantic similarity** | 50% | Dense + lexical relevance, fused via RRF |
 | **Recency** | 25% | Exponential decay with 14-day half-life — recent decisions rank higher |
 | **Kind weight** | 15% | Distilled memories (1.3x) rank above raw session chunks (1.0x) |
 | **Quality** | 10% | Bayesian score from implicit feedback — memories the agent actually uses rank higher |
@@ -110,10 +130,11 @@ Memories are automatically classified as `decision`, `bugfix`, `lesson`, `snippe
 memor dashboard
 ```
 
-Shows:
-- **Memory bank** — session chunks, distilled memories, projects tracked
-- **Context efficiency** — overhead %, recall precision, quality scores per session
-- **Per-project breakdown** — which projects have the most context
+Dark fintech-inspired UI showing:
+- **Hero metrics** — total memories, recall count, avg latency, coverage — with sparkline bars
+- **Daily recall activity** — stacked bar chart of hits vs misses over time
+- **Session efficiency** — real token savings measured from API usage data (avg tokens/turn with vs without recall)
+- **Per-project breakdown** — artifact counts, token totals, last activity
 - **Recent recalls** — every hook event with scores, latency, and status
 
 ---
@@ -125,6 +146,11 @@ memor help                           Print the full manual
 memor install-hook                   Install Claude Code hook + download model
 memor daemon                         Auto-ingest + distill (background watcher)
 memor dashboard                      Web dashboard on localhost:8420
+memor version                        Print installed version
+memor service install                Run daemon as background service (launchd/systemd)
+memor service stop                   Stop the background service
+memor service uninstall              Remove the background service
+memor service status                 Check if the service is running
 memor query <text>                   Search memories from the CLI
 memor reingest                       Wipe DB and re-ingest everything
 memor reingest --project <name>      Re-ingest only one project
@@ -156,16 +182,17 @@ memor/
 +-- feedback.py           Implicit feedback analyzer (usage detection)
 |
 +-- retrieve/
-|   +-- retriever.py      Hybrid scoring: similarity + recency + kind + quality
+|   +-- retriever.py      Hybrid retrieval (dense + BM25, RRF) + relevance gate + scoring
 |
 +-- store/
-|   +-- sqlite_store.py   SQLite + sqlite-vec (WAL mode, dimension safety)
+|   +-- sqlite_store.py   SQLite + sqlite-vec + FTS5 (WAL mode, dimension safety)
 |
 +-- embed/
 |   +-- local.py          model2vec (potion-base-8M, 256-dim, ~60MB)
 |   +-- api.py            OpenAI-compatible embedding API (optional)
 |   +-- fake.py           Deterministic SHA-256 embedder (tests)
 |
++-- service.py            Background service management (launchd/systemd)
 +-- dashboard/
 |   +-- server.py         FastAPI dashboard backend
 |   +-- static/index.html Self-contained dashboard (no CDN deps)
@@ -190,7 +217,7 @@ skill/recall.py            Standalone recall script
 **Nothing leaves your machine.** In the default configuration:
 
 - **No telemetry, no analytics, no phone-home.** Zero outbound network calls.
-- **Embeddings run locally** via model2vec ONNX (one-time model download from HuggingFace — no user data sent).
+- **Embeddings run locally** via model2vec static token embeddings — no inference runtime, no GPU (one-time model download from HuggingFace — no user data sent).
 - **Hook transport is a Unix socket** (`~/.memor/hook.sock`), not a network port.
 - **Dashboard binds localhost only.**
 
@@ -226,7 +253,7 @@ cd memor-ai
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest  # 153 tests
+pytest  # 179 tests
 ```
 
 ---

memor_cli-0.3.0/memor/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{memor_cli-0.1.1 → memor_cli-0.3.0}/memor/cli.py

@@ -9,6 +9,8 @@ from memor.types import Scope
 from memor.ingest.claude_code import parse_transcript
 
 app = typer.Typer(no_args_is_help=True)
+service_app = typer.Typer(help="Manage the memor daemon as a background service.")
+app.add_typer(service_app, name="service")
 
 def _db_path(db: str) -> str:
     return str(Path(db).expanduser())
@@ -42,14 +44,21 @@ HELP_TEXT = """\
 memor — measured memory for coding agents
 
 GETTING STARTED
-  memor install-hook     Install the Claude Code recall hook + download model
-  memor daemon           Start the background watcher (ingests + distills)
-  memor dashboard        Open the web dashboard at localhost:8420
+  memor install-hook        Install the Claude Code recall hook + download model
+  memor service install     Start the daemon as a background service
+  memor dashboard           Open the web dashboard at localhost:8420
+
+SERVICE MANAGEMENT
+  memor service install     Install and start as a background service (survives reboots)
+  memor service status      Check if the daemon is running
+  memor service stop        Stop the service (restarts on next login)
+  memor service uninstall   Stop and remove the service completely
+  memor daemon              Run the daemon in the foreground (alternative to service)
 
 QUERYING
-  memor query <text>     Search memories from the command line
-    --project <name>     Scope to a specific project
-    --k <n>              Number of results (default: 8)
+  memor query <text>        Search memories from the command line
+    --project <name>        Scope to a specific project
+    --k <n>                 Number of results (default: 8)
 
 INGESTION
   memor ingest-cc <file>           Ingest a single transcript
@@ -66,6 +75,7 @@ MAINTENANCE
   memor scan                       Audit DB for leaked secrets
   memor scan --purge               Redact secrets in place
   memor setup-model                Download/retry the embedding model (~60MB)
+  memor version                    Print the installed version
 
 EVALUATION
   memor eval <cases.json>          Run eval suite
@@ -77,10 +87,10 @@ CONFIGURATION
   No configuration needed — just install, hook, and run the daemon.
 
 EXAMPLES
-  memor install-hook && memor daemon    # one-time setup
+  memor install-hook && memor service install  # one-time setup
   memor query "auth flow" --project my-app
-  memor reingest --project my-app -y    # refresh one project
-  memor dashboard                       # see stats at localhost:8420
+  memor reingest --project my-app -y           # refresh one project
+  memor dashboard                              # see stats at localhost:8420
 """
 
 
@@ -438,7 +448,8 @@ def install_hook():
         typer.echo("  retry later with: memor setup-model")
     typer.echo()
     typer.echo("Next steps:")
-    typer.echo("  1. Start the daemon: memor daemon")
+    typer.echo("  1. Start the daemon: memor service install")
+    typer.echo("     (or foreground: memor daemon)")
     typer.echo("  2. Open the dashboard: memor dashboard")
     typer.echo("  Everything works locally — no API keys needed.")
 
@@ -464,5 +475,47 @@ def dashboard(port: int = typer.Option(8420, help="Port to serve on"),
     uvicorn.run(app_instance, host="127.0.0.1", port=port, log_level="warning")
 
 
+@app.command("version")
+def version():
+    """Print the memor version."""
+    from memor import __version__
+    typer.echo(f"memor {__version__}")
+
+
+@service_app.command("install")
+def service_install():
+    """Install and start the daemon as a background service (survives reboots)."""
+    from memor.service import install
+    try:
+        typer.echo(install())
+    except FileNotFoundError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(1)
+    except Exception as e:
+        typer.echo(f"Failed to install service: {e}", err=True)
+        raise typer.Exit(1)
+
+
+@service_app.command("uninstall")
+def service_uninstall():
+    """Stop and remove the background service."""
+    from memor.service import uninstall
+    typer.echo(uninstall())
+
+
+@service_app.command("stop")
+def service_stop():
+    """Stop the background service (will restart on next login)."""
+    from memor.service import stop
+    typer.echo(stop())
+
+
+@service_app.command("status")
+def service_status():
+    """Show whether the daemon service is running."""
+    from memor.service import status
+    typer.echo(status())
+
+
 if __name__ == "__main__":
     app()

{memor_cli-0.1.1 → memor_cli-0.3.0}/memor/daemon.py

@@ -93,6 +93,15 @@ def ingest_file(path: Path, project: str, store: SqliteStore, embedder) -> int:
         return 0
     vecs = embedder.embed([a.text for a in arts])
     store.add_artifacts(arts, vecs)
+
+    from memor.ingest.claude_code import parse_session_usage
+    try:
+        usage = parse_session_usage(path, project)
+        if usage:
+            store.upsert_session_stats(usage)
+    except Exception:
+        pass
+
     return len(arts)
 
 

{memor_cli-0.1.1 → memor_cli-0.3.0}/memor/dashboard/server.py

@@ -114,6 +114,26 @@ def create_app(db_path: str | None = None) -> FastAPI:
             })
         return result
 
+    @app.get("/api/session-efficiency")
+    def session_efficiency():
+        store = _store()
+        return store.get_session_efficiency()
+
+    @app.get("/api/recall-trend")
+    def recall_trend(days: int = Query(30, ge=7, le=90)):
+        store = _store()
+        rows = store.db.execute("""
+            SELECT date(timestamp, 'unixepoch', 'localtime') as day,
+                   COUNT(*) as recalls,
+                   SUM(CASE WHEN hits_count > 0 THEN 1 ELSE 0 END) as hits,
+                   SUM(tokens_injected) as tokens,
+                   AVG(CASE WHEN hits_count > 0 THEN top_score END) as avg_score
+            FROM recall_log
+            WHERE timestamp >= unixepoch('now', ? || ' days')
+            GROUP BY day ORDER BY day
+        """, (f"-{days}",)).fetchall()
+        return [dict(r) for r in rows]
+
     @app.get("/api/health")
     def health():
         store = _store()