recall-cli 0.1.0__tar.gz

recall_cli-0.1.0/.env.example

@@ -0,0 +1,12 @@
+QDRANT_HOST=localhost
+QDRANT_PORT=6333
+COLLECTION_NAME=memories
+OLLAMA_BASE_URL=http://localhost:11434
+EMBED_MODEL=nomic-embed-text
+OLLAMA_EMBED_PATH=/api/embed
+API_HOST=127.0.0.1
+API_PORT=8100
+API_AUTH_TOKEN=
+MAX_TEXT_LENGTH=8000
+MAX_BATCH_SIZE=100
+HEALTH_CHECK_TIMEOUT_S=5

recall_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.env

recall_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anel Canto
+
+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.

recall_cli-0.1.0/Makefile

@@ -0,0 +1,40 @@
+.PHONY: up down serve dev test test-integration test-degraded test-all status install
+
+up:
+	docker run -d --name qdrant \
+		-p 127.0.0.1:6333:6333 \
+		-p 127.0.0.1:6334:6334 \
+		-v qdrant_data:/qdrant/storage \
+		qdrant/qdrant:v1.13.2 || docker start qdrant
+
+down:
+	docker stop qdrant && docker rm qdrant
+
+serve:
+	uv run uvicorn memory_api.main:app --host 127.0.0.1 --port 8100
+
+dev:
+	$(MAKE) up && $(MAKE) serve
+
+test:
+	uv run pytest tests/test_unit.py -v
+
+test-integration:
+	uv run pytest tests/test_integration.py -v
+
+test-degraded:
+	uv run pytest tests/test_degraded.py -v
+
+test-all:
+	uv run pytest tests/ -v
+
+status:
+	@curl -sf http://127.0.0.1:8100/health | python3 -m json.tool || echo "API not running"
+
+install:
+	@mkdir -p ~/.memories
+	@test -f ~/.memories/.env || cp .env.example ~/.memories/.env
+	uv sync
+	@echo ""
+	@echo "Installed. Run 'make dev' to start Qdrant + API server."
+	@echo "CLI available via: uv run recall --help"

recall_cli-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: recall-cli
+Version: 0.1.0
+Summary: A personal semantic memory system — store, search, and manage memories locally with vector embeddings
+Project-URL: Homepage, https://github.com/anelcanto/recall
+Project-URL: Repository, https://github.com/anelcanto/recall
+Project-URL: Issues, https://github.com/anelcanto/recall/issues
+Author-email: Anel Canto <anelcanto@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: pydantic-settings
+Requires-Dist: python-dotenv
+Requires-Dist: qdrant-client
+Requires-Dist: rich
+Requires-Dist: typer
+Requires-Dist: uvicorn[standard]
+Description-Content-Type: text/markdown
+
+# recall
+
+A personal semantic memory system. Store, search, and manage memories locally using vector embeddings.
+
+Everything runs on your machine: FastAPI server, Qdrant vector database (Docker), and Ollama for local embeddings. Zero cost, full privacy.
+
+## Install
+
+### From PyPI
+
+```bash
+pip install recall-cli
+```
+
+### From Homebrew
+
+```bash
+brew tap anelcanto/recall-cli
+brew install recall-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/anelcanto/recall.git
+cd recall
+./install.sh
+```
+
+Or the quick version:
+
+```bash
+make install
+```
+
+## Prerequisites
+
+- **Docker** — runs Qdrant vector database
+- **Ollama** — local embeddings (`brew install ollama && ollama pull nomic-embed-text`)
+- **uv** — Python package manager (`brew install uv`)
+
+## Quick start
+
+```bash
+# Start services
+make up        # Start Qdrant in Docker
+make serve     # Start API server (keep this running)
+
+# In another terminal
+recall add "The quick brown fox" --tag test
+recall search "fox"
+recall list
+recall status
+```
+
+## CLI
+
+```
+recall add "text" --tag work --source cli [--dedupe-key "..."]
+recall search "query" --top-k 10 [--no-text] [--output table|json]
+recall ingest <file> [--format lines|jsonl] [--source name] [--auto-dedupe]
+recall list [--limit 20] [--cursor ...] [--output table|json]
+recall delete <id>
+recall status
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RECALL_API_URL` | `http://127.0.0.1:8100` | API server URL |
+| `RECALL_API_TOKEN` | (none) | Bearer token for auth |
+
+## Architecture
+
+```
+recall CLI  -->  FastAPI server (:8100)  -->  Qdrant (Docker :6333)
+                       |
+                       v
+                 Ollama (:11434)
+                 nomic-embed-text
+```
+
+- **FastAPI** serves the HTTP API
+- **Qdrant** stores vectors and payloads
+- **Ollama** generates embeddings locally using `nomic-embed-text`
+- **CLI** talks to the API over HTTP
+
+User config lives in `~/.memories/.env`. Qdrant data persists in a Docker volume.
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/memory` | Store a memory |
+| `POST` | `/search` | Semantic search |
+| `POST` | `/ingest` | Batch import |
+| `GET` | `/memories` | List with pagination |
+| `DELETE` | `/memory/{id}` | Delete a memory |
+| `GET` | `/health` | Service health check |
+
+## Development
+
+```bash
+make test              # Unit tests (no services needed)
+make test-integration  # Integration tests (Qdrant + Ollama required)
+make test-degraded     # Degraded mode tests (Qdrant only)
+make test-all          # All tests
+```
+
+## License
+
+MIT

recall_cli-0.1.0/README.md

@@ -0,0 +1,113 @@
+# recall
+
+A personal semantic memory system. Store, search, and manage memories locally using vector embeddings.
+
+Everything runs on your machine: FastAPI server, Qdrant vector database (Docker), and Ollama for local embeddings. Zero cost, full privacy.
+
+## Install
+
+### From PyPI
+
+```bash
+pip install recall-cli
+```
+
+### From Homebrew
+
+```bash
+brew tap anelcanto/recall-cli
+brew install recall-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/anelcanto/recall.git
+cd recall
+./install.sh
+```
+
+Or the quick version:
+
+```bash
+make install
+```
+
+## Prerequisites
+
+- **Docker** — runs Qdrant vector database
+- **Ollama** — local embeddings (`brew install ollama && ollama pull nomic-embed-text`)
+- **uv** — Python package manager (`brew install uv`)
+
+## Quick start
+
+```bash
+# Start services
+make up        # Start Qdrant in Docker
+make serve     # Start API server (keep this running)
+
+# In another terminal
+recall add "The quick brown fox" --tag test
+recall search "fox"
+recall list
+recall status
+```
+
+## CLI
+
+```
+recall add "text" --tag work --source cli [--dedupe-key "..."]
+recall search "query" --top-k 10 [--no-text] [--output table|json]
+recall ingest <file> [--format lines|jsonl] [--source name] [--auto-dedupe]
+recall list [--limit 20] [--cursor ...] [--output table|json]
+recall delete <id>
+recall status
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RECALL_API_URL` | `http://127.0.0.1:8100` | API server URL |
+| `RECALL_API_TOKEN` | (none) | Bearer token for auth |
+
+## Architecture
+
+```
+recall CLI  -->  FastAPI server (:8100)  -->  Qdrant (Docker :6333)
+                       |
+                       v
+                 Ollama (:11434)
+                 nomic-embed-text
+```
+
+- **FastAPI** serves the HTTP API
+- **Qdrant** stores vectors and payloads
+- **Ollama** generates embeddings locally using `nomic-embed-text`
+- **CLI** talks to the API over HTTP
+
+User config lives in `~/.memories/.env`. Qdrant data persists in a Docker volume.
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/memory` | Store a memory |
+| `POST` | `/search` | Semantic search |
+| `POST` | `/ingest` | Batch import |
+| `GET` | `/memories` | List with pagination |
+| `DELETE` | `/memory/{id}` | Delete a memory |
+| `GET` | `/health` | Service health check |
+
+## Development
+
+```bash
+make test              # Unit tests (no services needed)
+make test-integration  # Integration tests (Qdrant + Ollama required)
+make test-degraded     # Degraded mode tests (Qdrant only)
+make test-all          # All tests
+```
+
+## License
+
+MIT

recall_cli-0.1.0/cli/recall_cli.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(name="recall", help="Personal semantic memory CLI")
+console = Console()
+
+DEFAULT_API_URL = "http://127.0.0.1:8100"
+
+
+def _get_api_url(api_url: Optional[str]) -> str:
+    return api_url or os.environ.get("RECALL_API_URL", DEFAULT_API_URL)
+
+
+def _get_token(token: Optional[str]) -> Optional[str]:
+    return token or os.environ.get("RECALL_API_TOKEN") or None
+
+
+def _build_headers(token: Optional[str]) -> dict:
+    h = {"Content-Type": "application/json"}
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    return h
+
+
+def _handle_error(resp: httpx.Response, api_url: str) -> None:
+    if resp.status_code in (200, 201):
+        return
+    try:
+        data = resp.json()
+        detail = data.get("detail", resp.text)
+    except Exception:
+        detail = resp.text
+    console.print(f"[red]Error {resp.status_code}:[/red] {detail}")
+    raise typer.Exit(1)
+
+
+def _connection_error(url: str) -> None:
+    console.print(
+        f"[red]Cannot reach recall service at {url}.[/red]\n"
+        f"Try: [bold]make serve[/bold] (from your recall project directory)"
+    )
+    raise typer.Exit(1)
+
+
+def _is_tty() -> bool:
+    return sys.stdout.isatty()
+
+
+@app.command()
+def add(
+    text: str = typer.Argument(..., help="The memory text to store"),
+    tag: list[str] = typer.Option([], "--tag", "-t", help="Tag(s) to attach"),
+    source: str = typer.Option("cli", "--source", "-s", help="Source identifier"),
+    dedupe_key: Optional[str] = typer.Option(None, "--dedupe-key", "-d", help="Deduplication key"),
+    api_url: Optional[str] = typer.Option(None, "--api-url"),
+    token: Optional[str] = typer.Option(None, "--token"),
+):
+    """Store a memory."""
+    url = _get_api_url(api_url)
+    tok = _get_token(token)
+    payload = {"text": text, "tags": list(tag), "source": source, "dedupe_key": dedupe_key}
+
+    try:
+        resp = httpx.post(f"{url}/memory", json=payload, headers=_build_headers(tok), timeout=30)
+    except httpx.RequestError:
+        _connection_error(url)
+
+    _handle_error(resp, url)
+    data = resp.json()
+    console.print(f"[green]Stored[/green] id=[bold]{data['id']}[/bold] strategy={data['id_strategy']}")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    top_k: int = typer.Option(5, "--top-k", "-k"),
+    no_text: bool = typer.Option(False, "--no-text"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="table|json"),
+    api_url: Optional[str] = typer.Option(None, "--api-url"),
+    token: Optional[str] = typer.Option(None, "--token"),
+):
+    """Search memories by semantic similarity."""
+    url = _get_api_url(api_url)
+    tok = _get_token(token)
+    fmt = output or ("table" if _is_tty() else "json")
+    payload = {"query": query, "top_k": top_k, "include_text": not no_text}
+
+    try:
+        resp = httpx.post(f"{url}/search", json=payload, headers=_build_headers(tok), timeout=30)
+    except httpx.RequestError:
+        _connection_error(url)
+
+    _handle_error(resp, url)
+    results = resp.json().get("results", [])
+
+    if fmt == "json":
+        print(json.dumps(results, indent=2))
+        return
+
+    if not results:
+        console.print("[yellow]No results found.[/yellow]")
+        return
+
+    table = Table(title=f"Search: {query!r}")
+    table.add_column("Score", style="cyan", width=6)
+    table.add_column("ID", style="dim", width=36)
+    table.add_column("Tags")
+    table.add_column("Written At")
+    if not no_text:
+        table.add_column("Text")
+
+    for r in results:
+        row = [
+            f"{r['score']:.3f}",
+            r["id"],
+            ", ".join(r.get("tags", [])),
+            r.get("written_at", "")[:19],
+        ]
+        if not no_text:
+            row.append((r.get("text") or "")[:80])
+        table.add_row(*row)
+
+    console.print(table)
+
+
+@app.command()
+def ingest(
+    file: Path = typer.Argument(..., help="File to ingest"),
+    format: str = typer.Option("lines", "--format", "-f", help="lines|jsonl"),
+    source: str = typer.Option("ingest", "--source", "-s"),
+    auto_dedupe: bool = typer.Option(False, "--auto-dedupe"),
+    api_url: Optional[str] = typer.Option(None, "--api-url"),
+    token: Optional[str] = typer.Option(None, "--token"),
+):
+    """Ingest memories from a file."""
+    url = _get_api_url(api_url)
+    tok = _get_token(token)
+
+    if not file.exists():
+        console.print(f"[red]File not found:[/red] {file}")
+        raise typer.Exit(1)
+
+    raw = file.read_text(encoding="utf-8")
+    items: list[dict] = []
+
+    if format == "jsonl":
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            obj = json.loads(line)
+            items.append(obj)
+    else:
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            items.append({"text": line, "tags": [], "source": source})
+
+    if auto_dedupe:
+        for item in items:
+            src = item.get("source", source)
+            item["dedupe_key"] = hashlib.sha256(
+                (item["text"] + src).encode()
+            ).hexdigest()
+
+    batch_size = 100
+    total_succeeded = 0
+    total_failed = 0
+    all_errors: list[dict] = []
+
+    for i in range(0, len(items), batch_size):
+        batch = items[i : i + batch_size]
+        try:
+            resp = httpx.post(
+                f"{url}/ingest",
+                json={"items": batch},
+                headers=_build_headers(tok),
+                timeout=60,
+            )
+        except httpx.RequestError:
+            _connection_error(url)
+
+        _handle_error(resp, url)
+        data = resp.json()
+        total_succeeded += data.get("succeeded", 0)
+        total_failed += data.get("failed", 0)
+        for err in data.get("errors", []):
+            err["index"] += i
+            all_errors.append(err)
+
+    console.print(
+        f"[green]Ingested[/green] {total_succeeded} succeeded, "
+        f"[{'red' if total_failed else 'green'}]{total_failed}[/{'red' if total_failed else 'green'}] failed"
+    )
+    for err in all_errors:
+        console.print(f"  [red]Error[/red] item {err['index']}: {err['error']}")
+
+
+@app.command(name="list")
+def list_memories(
+    limit: int = typer.Option(20, "--limit", "-l"),
+    cursor: Optional[str] = typer.Option(None, "--cursor"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="table|json"),
+    api_url: Optional[str] = typer.Option(None, "--api-url"),
+    token: Optional[str] = typer.Option(None, "--token"),
+):
+    """List stored memories."""
+    url = _get_api_url(api_url)
+    tok = _get_token(token)
+    fmt = output or ("table" if _is_tty() else "json")
+
+    params: dict = {"limit": limit}
+    if cursor:
+        params["cursor"] = cursor
+
+    try:
+        resp = httpx.get(f"{url}/memories", params=params, headers=_build_headers(tok), timeout=30)
+    except httpx.RequestError:
+        _connection_error(url)
+
+    _handle_error(resp, url)
+    data = resp.json()
+    memories = data.get("memories", [])
+    next_cursor = data.get("next_cursor")
+
+    if fmt == "json":
+        print(json.dumps(data, indent=2))
+        return
+
+    if not memories:
+        console.print("[yellow]No memories found.[/yellow]")
+        return
+
+    table = Table(title="Memories")
+    table.add_column("ID", style="dim", width=36)
+    table.add_column("Tags")
+    table.add_column("Source")
+    table.add_column("Written At")
+    table.add_column("Text")
+
+    for m in memories:
+        table.add_row(
+            m["id"],
+            ", ".join(m.get("tags", [])),
+            m.get("source", ""),
+            m.get("written_at", "")[:19],
+            (m.get("text") or "")[:60],
+        )
+
+    console.print(table)
+    if next_cursor:
+        console.print(f"\n[dim]Next cursor:[/dim] {next_cursor}")
+
+
+@app.command()
+def delete(
+    id: str = typer.Argument(..., help="Memory ID to delete"),
+    api_url: Optional[str] = typer.Option(None, "--api-url"),
+    token: Optional[str] = typer.Option(None, "--token"),
+):
+    """Delete a memory by ID."""
+    url = _get_api_url(api_url)
+    tok = _get_token(token)
+
+    try:
+        resp = httpx.delete(f"{url}/memory/{id}", headers=_build_headers(tok), timeout=30)
+    except httpx.RequestError:
+        _connection_error(url)
+
+    _handle_error(resp, url)
+    console.print(f"[green]Deleted[/green] {id}")
+
+
+@app.command()
+def status(
+    api_url: Optional[str] = typer.Option(None, "--api-url"),
+    token: Optional[str] = typer.Option(None, "--token"),
+):
+    """Show API health status."""
+    url = _get_api_url(api_url)
+
+    try:
+        resp = httpx.get(f"{url}/health", timeout=10)
+    except httpx.RequestError:
+        _connection_error(url)
+
+    data = resp.json()
+    color = "green" if data.get("status") == "ok" else "yellow" if data.get("status") == "degraded" else "red"
+    console.print(f"[{color}]Status:[/{color}] {data.get('status')}")
+    console.print(f"  Qdrant: {data.get('qdrant')}")
+    console.print(f"  Ollama: {data.get('ollama')}")
+
+
+if __name__ == "__main__":
+    app()

recall_cli-0.1.0/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  qdrant:
+    image: qdrant/qdrant:v1.13.2
+    ports:
+      - "127.0.0.1:6333:6333"
+      - "127.0.0.1:6334:6334"
+    volumes:
+      - qdrant_data:/qdrant/storage
+    restart: unless-stopped
+
+volumes:
+  qdrant_data: