loreconvo-cli 0.1.0a1__tar.gz

loreconvo_cli-0.1.0a1/LICENSE

@@ -0,0 +1,93 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Labyrinth Analytics Consulting
+Licensed Work:        LoreConvo v0.3.2
+                      The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
+Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
+                      subject to the following limitation: you may store no more than
+                      50 sessions in total across all databases on your machine. Any
+                      use that exceeds this limit, or any commercial use, requires a
+                      paid license from the Licensor.
+Change Date:          2030-03-31
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: info@labyrinthanalyticsconsulting.com
+
+---
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive a copy of the Licensed Work in
+combination with other programs, as part of a larger work, or packaged by a
+third party, and you receive the Licensed Work under a different license from
+the one described in this License, you are required to comply with the license
+applicable to you.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided under this License:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

loreconvo_cli-0.1.0a1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: loreconvo-cli
+Version: 0.1.0a1
+Summary: Command-line interface for LoreConvo cross-surface session memory
+Author: Labyrinth Analytics Consulting
+License: Business Source License 1.1
+        
+        Parameters
+        
+        Licensor:             Labyrinth Analytics Consulting
+        Licensed Work:        LoreConvo v0.3.2
+                              The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
+        Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
+                              subject to the following limitation: you may store no more than
+                              50 sessions in total across all databases on your machine. Any
+                              use that exceeds this limit, or any commercial use, requires a
+                              paid license from the Licensor.
+        Change Date:          2030-03-31
+        Change License:       Apache License, Version 2.0
+        
+        For information about alternative licensing arrangements for the Licensed Work,
+        please contact: info@labyrinthanalyticsconsulting.com
+        
+        ---
+        
+        Business Source License 1.1
+        
+        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+        "Business Source License" is a trademark of MariaDB Corporation Ab.
+        
+        Terms
+        
+        The Licensor hereby grants you the right to copy, modify, create derivative
+        works, redistribute, and make non-production use of the Licensed Work. The
+        Licensor may make an Additional Use Grant, above, permitting limited production
+        use.
+        
+        Effective on the Change Date, or the fourth anniversary of the first publicly
+        available distribution of a specific version of the Licensed Work under this
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph
+        above terminate.
+        
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
+        
+        All copies of the original and modified Licensed Work, and derivative works
+        of the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
+        
+        You must conspicuously display this License on each original or modified copy
+        of the Licensed Work. If you receive a copy of the Licensed Work in
+        combination with other programs, as part of a larger work, or packaged by a
+        third party, and you receive the Licensed Work under a different license from
+        the one described in this License, you are required to comply with the license
+        applicable to you.
+        
+        Any use of the Licensed Work in violation of this License will automatically
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
+        
+        This License does not grant you any right in any trademark or logo of
+        Licensor or its affiliates (provided that you may use a trademark or logo of
+        Licensor as expressly required by this License).
+        
+        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+        TITLE.
+        
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided under this License:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or a later version,
+           where "compatible" means that software provided under the Change License can
+           be included in a program with software provided under GPL Version 2.0 or a
+           later version. Licensor may specify additional Change Licenses without
+           limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+        
+Project-URL: Homepage, https://github.com/labyrinth-analytics/loreconvo-cli
+Project-URL: Repository, https://github.com/labyrinth-analytics/loreconvo-cli
+Project-URL: Bug Tracker, https://github.com/labyrinth-analytics/loreconvo-cli/issues
+Keywords: mcp,claude,memory,cli,sessions,ai-tools,claude-plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: Other/Proprietary 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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer==0.13.1
+Provides-Extra: server
+Requires-Dist: loreconvo==0.7.1; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Dynamic: license-file
+
+# loreconvo-cli v0.1.0
+
+Command-line interface for LoreConvo session memory.
+
+Search, list, read, and save your LoreConvo sessions from the terminal -- no MCP
+server or Claude session required.
+
+```bash
+pip install loreconvo-cli
+
+loreconvo-cli search "rental property"
+loreconvo-cli list --project side_hustle
+loreconvo-cli read --id <session-uuid>
+```
+
+## Commands
+
+| Command | Free tier | Description |
+|---------|-----------|-------------|
+| `search <query>` | Yes | Full-text search across sessions |
+| `list` | Yes | List recent sessions |
+| `read` | Yes | Read session detail (full summary + decisions) |
+| `save` | [server] extra | Save a new session |
+
+The `save` command requires `pip install "loreconvo-cli[server]"` (installs the
+`loreconvo` package as a dependency).
+
+## Platform
+
+macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported.
+
+## Full Documentation
+
+See [INSTALL.md](INSTALL.md) for complete usage, flags, environment variables,
+and troubleshooting.
+
+## License
+
+Business Source License 1.1 -- Labyrinth Analytics Consulting

loreconvo_cli-0.1.0a1/README.md

@@ -0,0 +1,39 @@
+# loreconvo-cli v0.1.0
+
+Command-line interface for LoreConvo session memory.
+
+Search, list, read, and save your LoreConvo sessions from the terminal -- no MCP
+server or Claude session required.
+
+```bash
+pip install loreconvo-cli
+
+loreconvo-cli search "rental property"
+loreconvo-cli list --project side_hustle
+loreconvo-cli read --id <session-uuid>
+```
+
+## Commands
+
+| Command | Free tier | Description |
+|---------|-----------|-------------|
+| `search <query>` | Yes | Full-text search across sessions |
+| `list` | Yes | List recent sessions |
+| `read` | Yes | Read session detail (full summary + decisions) |
+| `save` | [server] extra | Save a new session |
+
+The `save` command requires `pip install "loreconvo-cli[server]"` (installs the
+`loreconvo` package as a dependency).
+
+## Platform
+
+macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported.
+
+## Full Documentation
+
+See [INSTALL.md](INSTALL.md) for complete usage, flags, environment variables,
+and troubleshooting.
+
+## License
+
+Business Source License 1.1 -- Labyrinth Analytics Consulting

loreconvo_cli-0.1.0a1/loreconvo_cli/__init__.py

@@ -0,0 +1,3 @@
+"""LoreConvo CLI -- standalone command-line interface for LoreConvo session memory."""
+
+__version__ = "0.1.0"

loreconvo_cli-0.1.0a1/loreconvo_cli/_db_path.py

@@ -0,0 +1,114 @@
+import os
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+DEFAULT_LORECONVO_DIR = Path.home() / ".loreconvo"
+DEFAULT_DB_PATH = DEFAULT_LORECONVO_DIR / "sessions.db"
+
+_KNOWN_DB_DIRS = frozenset({
+    str(Path.home() / ".loreconvo"),
+    str(Path.home() / ".loredocs"),
+    str(Path.home() / ".lorecap"),
+})
+
+
+def _sanitize_fts5(query: str) -> str:
+    """Strip FTS5 special chars to prevent injection. Returns sanitized query."""
+    sanitized = re.sub(r'["\*\^\(\)\[\]]', ' ', query).strip()
+    return sanitized if sanitized else '""'
+
+
+def validate_db_path(path_str: str) -> Path:
+    """Validate a --db-path argument.
+
+    Raises SystemExit(1) with a clear message on violation rather than
+    typer.BadParameter so it works outside typer context (tests, direct calls).
+    """
+    import typer
+
+    p = Path(path_str).expanduser().resolve()
+
+    if p.suffix != ".db":
+        raise typer.BadParameter(f"DB path must end in .db (got: {p.suffix!r})")
+
+    home = Path.home().resolve()
+    try:
+        p.relative_to(home)
+    except ValueError:
+        if not os.environ.get("LORECONVO_ALLOW_EXTERNAL_DB"):
+            raise typer.BadParameter(
+                f"DB path must be under {home}. "
+                "Set LORECONVO_ALLOW_EXTERNAL_DB=1 to override (CI/testing only)."
+            )
+
+    if str(p.parent) not in _KNOWN_DB_DIRS:
+        if not os.environ.get("LORECONVO_ALLOW_EXTERNAL_DB"):
+            raise typer.BadParameter(
+                f"DB must be in one of: {sorted(_KNOWN_DB_DIRS)}.\n"
+                "Set LORECONVO_ALLOW_EXTERNAL_DB=1 to use a custom directory."
+            )
+        print(f"[warn] external DB path in use: {p}", file=sys.stderr)
+
+    if os.environ.get("LORECONVO_ALLOW_EXTERNAL_DB"):
+        print(
+            "[warn] LORECONVO_ALLOW_EXTERNAL_DB is set; external DB path override is active.",
+            file=sys.stderr,
+        )
+
+    if p.exists() and hasattr(os, "getuid"):
+        if os.stat(p).st_uid != os.getuid():
+            raise typer.BadParameter(f"DB at {p} is not owned by current user.")
+
+    if p.exists() and not p.is_file():
+        raise typer.BadParameter(f"{p} exists but is not a file.")
+
+    return p
+
+
+def get_db_path(custom_path: str | None = None) -> Path:
+    """Resolve DB path: --db-path arg > LORECONVO_DB_PATH env > default."""
+    if custom_path:
+        return validate_db_path(custom_path)
+    env_path = os.environ.get("LORECONVO_DB_PATH")
+    if env_path:
+        return validate_db_path(env_path)
+    return DEFAULT_DB_PATH
+
+
+def open_db(db_path: Path) -> sqlite3.Connection:
+    """Open a read-only SQLite connection with WAL mode and permissions check.
+
+    Exits with a helpful error if the DB does not exist.
+    """
+    if not db_path.exists():
+        print(
+            f"\nError: LoreConvo database not found at {db_path}\n\n"
+            "The database is created automatically when you first use the LoreConvo MCP server.\n\n"
+            "Quick setup:\n"
+            "  1. pip install loreconvo-cli[server]       # install CLI + server\n"
+            "  2. Add loreconvo to your MCP client config  # (see: pip show loreconvo)\n"
+            "  3. Start a session to initialize the DB     # MCP creates DB on first use\n"
+            "  4. Then run: loreconvo-cli search 'keyword'\n\n"
+            "Or initialize directly: loreconvo-cli server --init\n\n"
+            "Set LORECONVO_DB_PATH=/path/to/sessions.db to use a custom DB location.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    if hasattr(os, "stat"):
+        mode = db_path.stat().st_mode & 0o777
+        if mode & 0o177:
+            print(
+                f"[warn] DB file permissions are broader than 0600: {db_path}  "
+                f"(current: {oct(mode)}). "
+                f"Fix with: chmod 600 {db_path}",
+                file=sys.stderr,
+            )
+
+    conn = sqlite3.connect(str(db_path), timeout=30)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=30000")
+    conn.row_factory = sqlite3.Row
+    return conn

loreconvo_cli-0.1.0a1/loreconvo_cli/_platform_check.py

@@ -0,0 +1,33 @@
+import platform
+import sys
+
+_SUPPORTED = {
+    ("darwin", "x86_64"),
+    ("darwin", "arm64"),
+    ("linux", "x86_64"),
+}
+
+
+def check_platform() -> None:
+    """Exit with a clear error on unsupported platforms. Called first in main()."""
+    plat = "darwin" if sys.platform == "darwin" else "linux"
+    key = (plat, platform.machine())
+    if key not in _SUPPORTED:
+        print(
+            f"ERROR: loreconvo-cli is not supported on {sys.platform}/{platform.machine()}.\n"
+            "Supported: macOS (x86_64, arm64), Linux x86_64 (glibc).\n"
+            "Windows and musl/Alpine are not supported in v0.1.x.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    if sys.platform == "linux":
+        try:
+            proc_ver = open("/proc/version").read()
+            if "Microsoft" in proc_ver or "microsoft" in proc_ver:
+                print(
+                    "[warn] WSL detected. DB path defaults to WSL filesystem. "
+                    "Windows-host DB paths are not supported.",
+                    file=sys.stderr,
+                )
+        except OSError:
+            pass

loreconvo_cli-0.1.0a1/loreconvo_cli/_schema_compat.py

@@ -0,0 +1,40 @@
+import sqlite3
+import sys
+
+# Schema version range this CLI was tested against.
+# user_version 0 = unversioned (pre-migration DBs) -- treated as compatible.
+CLI_MIN_SCHEMA_VERSION = 0
+CLI_MAX_WRITE_VERSION = 8
+CLI_MAX_READ_VERSION = 10
+
+
+def check_schema_compatibility(conn: sqlite3.Connection) -> str:
+    """Check PRAGMA user_version against supported range.
+
+    Returns 'normal' or 'read_only'. Exits on incompatible schema.
+    """
+    try:
+        version = conn.execute("PRAGMA user_version").fetchone()[0]
+    except sqlite3.Error:
+        version = 0
+
+    if version > CLI_MAX_READ_VERSION:
+        print(
+            f"Error: DB schema v{version} is newer than loreconvo-cli supports "
+            f"(max readable: {CLI_MAX_READ_VERSION}).\n"
+            "Upgrade loreconvo-cli: pip install -U loreconvo-cli",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    if version > CLI_MAX_WRITE_VERSION:
+        print(
+            f"[warn] DB schema v{version} is newer than CLI write support "
+            f"(max writable: {CLI_MAX_WRITE_VERSION}). "
+            "Running in read-only mode. "
+            "Upgrade loreconvo-cli[server] for full write support.",
+            file=sys.stderr,
+        )
+        return "read_only"
+
+    return "normal"

loreconvo_cli-0.1.0a1/loreconvo_cli/_write_guard.py

@@ -0,0 +1,21 @@
+import importlib.util
+import sys
+
+
+def _has_server_package() -> bool:
+    """Check if the loreconvo server package is installed."""
+    return importlib.util.find_spec("loreconvo") is not None
+
+
+def require_write_capability(operation: str) -> None:
+    """Exit with a clear error if loreconvo server package is not installed.
+
+    Call this as the first line of every write command handler before any DB access.
+    """
+    if not _has_server_package():
+        print(
+            f"Error: '{operation}' requires write access.\n"
+            "Install the server package: pip install loreconvo-cli[server]",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)

loreconvo_cli-0.1.0a1/loreconvo_cli/main.py

@@ -0,0 +1,239 @@
+"""LoreConvo CLI -- cross-surface session memory command line interface.
+
+Free-tier operations only. Pro features require the LoreConvo MCP server.
+"""
+
+import enum
+import json
+import re
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+
+from ._db_path import get_db_path, open_db, _sanitize_fts5
+from ._platform_check import check_platform
+from ._schema_compat import check_schema_compatibility
+from ._write_guard import require_write_capability
+
+app = typer.Typer(
+    name="loreconvo-cli",
+    help=(
+        "LoreConvo -- cross-surface session memory.\n\n"
+        "Free-tier CLI (read + save operations).\n"
+        "Pro features require the MCP server: pip install loreconvo-cli[server]"
+    ),
+    no_args_is_help=True,
+)
+
+
+class FeatureSet(str, enum.Enum):
+    FREE = "free"
+    PRO = "pro"
+
+
+def _get_feature_set() -> FeatureSet:
+    """Return the active feature set. v0.1.x always returns FREE."""
+    return FeatureSet.FREE
+
+
+_DB_PATH_OPTION = typer.Option(
+    None, "--db-path", help="Path to sessions.db (overrides LORECONVO_DB_PATH)"
+)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query (full-text)"),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max results"),
+    offset: int = typer.Option(0, "--offset", help="Skip first N results"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Filter by project"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """Search sessions by keyword."""
+    path = get_db_path(db_path)
+    conn = open_db(path)
+    check_schema_compatibility(conn)
+
+    safe_q = _sanitize_fts5(query)
+    like_q = f"%{query}%"
+    try:
+        if project:
+            rows = conn.execute(
+                "SELECT id, title, surface, project, start_date, summary FROM sessions "
+                "WHERE project = ? AND (title LIKE ? OR summary LIKE ?) "
+                "ORDER BY start_date DESC LIMIT ? OFFSET ?",
+                (project, like_q, like_q, limit, offset),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT id, title, surface, project, start_date, summary FROM sessions "
+                "WHERE title LIKE ? OR summary LIKE ? OR tags LIKE ? "
+                "ORDER BY start_date DESC LIMIT ? OFFSET ?",
+                (like_q, like_q, like_q, limit, offset),
+            ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        typer.echo(f"No sessions found for: {query!r}")
+        return
+    for row in rows:
+        _print_session_line(dict(row))
+    typer.echo(f"\n{len(rows)} result(s)")
+
+
+@app.command(name="list")
+def list_sessions(
+    limit: int = typer.Option(10, "--limit", "-n", help="Max sessions to show"),
+    offset: int = typer.Option(0, "--offset", help="Skip first N sessions"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Filter by project"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """List recent sessions."""
+    path = get_db_path(db_path)
+    conn = open_db(path)
+    check_schema_compatibility(conn)
+
+    try:
+        if project:
+            rows = conn.execute(
+                "SELECT id, title, surface, project, start_date FROM sessions "
+                "WHERE project = ? ORDER BY start_date DESC LIMIT ? OFFSET ?",
+                (project, limit, offset),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT id, title, surface, project, start_date FROM sessions "
+                "ORDER BY start_date DESC LIMIT ? OFFSET ?",
+                (limit, offset),
+            ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        typer.echo("No sessions found.")
+        return
+    for row in rows:
+        _print_session_line(dict(row))
+    typer.echo(f"\n{len(rows)} session(s)")
+
+
+@app.command()
+def read(
+    id: Optional[str] = typer.Option(None, "--id", help="Session UUID"),
+    limit: int = typer.Option(5, "--limit", "-n", help="Sessions to show (without --id)"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """Read one session by UUID, or list recent sessions with full detail."""
+    path = get_db_path(db_path)
+    conn = open_db(path)
+    check_schema_compatibility(conn)
+
+    try:
+        if id:
+            if not re.fullmatch(r"[0-9a-zA-Z\-]{1,64}", id):
+                typer.echo("Error: --id must be a valid session UUID.", err=True)
+                raise typer.Exit(1)
+            row = conn.execute(
+                "SELECT id, title, surface, project, start_date, summary, decisions, "
+                "open_questions, tags FROM sessions WHERE id = ?",
+                (id,),
+            ).fetchone()
+            if not row:
+                typer.echo(f"Session not found: {id!r}", err=True)
+                raise typer.Exit(1)
+            _print_session_detail(dict(row))
+        else:
+            rows = conn.execute(
+                "SELECT id, title, surface, project, start_date, summary, decisions, "
+                "open_questions, tags FROM sessions ORDER BY start_date DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            for row in rows:
+                _print_session_detail(dict(row))
+    finally:
+        conn.close()
+
+
+@app.command()
+def save(
+    title: str = typer.Option(..., "--title", "-t", help="Session title"),
+    surface: str = typer.Option(..., "--surface", "-s", help="Surface (code/cowork/chat)"),
+    summary: str = typer.Option(..., "--summary", "-m", help="Session summary"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project name"),
+    tags: Optional[List[str]] = typer.Option(None, "--tags", help="Tags (repeatable)"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """Save a session. Requires loreconvo-cli[server]."""
+    require_write_capability("save")
+
+    from loreconvo.core.database import SessionDatabase
+    from loreconvo.core.models import Session
+    from loreconvo.core.config import Config
+
+    path = get_db_path(db_path)
+    if db_path:
+        import os
+        os.environ["LORECONVO_DB_PATH"] = str(path)
+
+    cfg = Config()
+    db = SessionDatabase(cfg)
+    session = Session(
+        title=title,
+        surface=surface,
+        summary=summary,
+        project=project,
+        tags=list(tags) if tags else [],
+    )
+    session_id = db.save_session(session)
+    typer.echo(f"[OK] Saved session: {session_id}")
+    typer.echo(f"  Title: {title}")
+    if project:
+        typer.echo(f"  Project: {project}")
+
+
+def _print_session_line(row: dict) -> None:
+    project_str = f" [{row['project']}]" if row.get("project") else ""
+    date_str = str(row.get("start_date", ""))[:10]
+    typer.echo(f"  {date_str}  {str(row.get('surface', '')):8s}{project_str}  {row.get('title', '')}")
+    typer.echo(f"    id: {row.get('id', '')}")
+
+
+def _print_session_detail(row: dict) -> None:
+    typer.echo(f"\n--- {row.get('title', '')} ---")
+    typer.echo(f"  id:      {row.get('id', '')}")
+    typer.echo(f"  date:    {str(row.get('start_date', ''))[:10]}")
+    typer.echo(f"  surface: {row.get('surface', '')}")
+    if row.get("project"):
+        typer.echo(f"  project: {row['project']}")
+    if row.get("summary"):
+        typer.echo(f"  summary: {row['summary'][:300]}")
+    if row.get("decisions"):
+        try:
+            decisions = json.loads(row["decisions"]) if isinstance(row["decisions"], str) else row["decisions"]
+            if decisions:
+                typer.echo("  decisions:")
+                for d in (decisions or [])[:3]:
+                    typer.echo(f"    - {d}")
+        except (json.JSONDecodeError, TypeError):
+            pass
+    if row.get("open_questions"):
+        try:
+            qs = json.loads(row["open_questions"]) if isinstance(row["open_questions"], str) else row["open_questions"]
+            if qs:
+                typer.echo("  open_questions:")
+                for q in (qs or [])[:3]:
+                    typer.echo(f"    ? {q}")
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+
+def main() -> None:
+    check_platform()
+    app()
+
+
+if __name__ == "__main__":
+    main()

loreconvo_cli-0.1.0a1/loreconvo_cli.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: loreconvo-cli
+Version: 0.1.0a1
+Summary: Command-line interface for LoreConvo cross-surface session memory
+Author: Labyrinth Analytics Consulting
+License: Business Source License 1.1
+        
+        Parameters
+        
+        Licensor:             Labyrinth Analytics Consulting
+        Licensed Work:        LoreConvo v0.3.2
+                              The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
+        Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
+                              subject to the following limitation: you may store no more than
+                              50 sessions in total across all databases on your machine. Any
+                              use that exceeds this limit, or any commercial use, requires a
+                              paid license from the Licensor.
+        Change Date:          2030-03-31
+        Change License:       Apache License, Version 2.0
+        
+        For information about alternative licensing arrangements for the Licensed Work,
+        please contact: info@labyrinthanalyticsconsulting.com
+        
+        ---
+        
+        Business Source License 1.1
+        
+        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+        "Business Source License" is a trademark of MariaDB Corporation Ab.
+        
+        Terms
+        
+        The Licensor hereby grants you the right to copy, modify, create derivative
+        works, redistribute, and make non-production use of the Licensed Work. The
+        Licensor may make an Additional Use Grant, above, permitting limited production
+        use.
+        
+        Effective on the Change Date, or the fourth anniversary of the first publicly
+        available distribution of a specific version of the Licensed Work under this
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph
+        above terminate.
+        
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
+        
+        All copies of the original and modified Licensed Work, and derivative works
+        of the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
+        
+        You must conspicuously display this License on each original or modified copy
+        of the Licensed Work. If you receive a copy of the Licensed Work in
+        combination with other programs, as part of a larger work, or packaged by a
+        third party, and you receive the Licensed Work under a different license from
+        the one described in this License, you are required to comply with the license
+        applicable to you.
+        
+        Any use of the Licensed Work in violation of this License will automatically
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
+        
+        This License does not grant you any right in any trademark or logo of
+        Licensor or its affiliates (provided that you may use a trademark or logo of
+        Licensor as expressly required by this License).
+        
+        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+        TITLE.
+        
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided under this License:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or a later version,
+           where "compatible" means that software provided under the Change License can
+           be included in a program with software provided under GPL Version 2.0 or a
+           later version. Licensor may specify additional Change Licenses without
+           limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+        
+Project-URL: Homepage, https://github.com/labyrinth-analytics/loreconvo-cli
+Project-URL: Repository, https://github.com/labyrinth-analytics/loreconvo-cli
+Project-URL: Bug Tracker, https://github.com/labyrinth-analytics/loreconvo-cli/issues
+Keywords: mcp,claude,memory,cli,sessions,ai-tools,claude-plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: Other/Proprietary 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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer==0.13.1
+Provides-Extra: server
+Requires-Dist: loreconvo==0.7.1; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Dynamic: license-file
+
+# loreconvo-cli v0.1.0
+
+Command-line interface for LoreConvo session memory.
+
+Search, list, read, and save your LoreConvo sessions from the terminal -- no MCP
+server or Claude session required.
+
+```bash
+pip install loreconvo-cli
+
+loreconvo-cli search "rental property"
+loreconvo-cli list --project side_hustle
+loreconvo-cli read --id <session-uuid>
+```
+
+## Commands
+
+| Command | Free tier | Description |
+|---------|-----------|-------------|
+| `search <query>` | Yes | Full-text search across sessions |
+| `list` | Yes | List recent sessions |
+| `read` | Yes | Read session detail (full summary + decisions) |
+| `save` | [server] extra | Save a new session |
+
+The `save` command requires `pip install "loreconvo-cli[server]"` (installs the
+`loreconvo` package as a dependency).
+
+## Platform
+
+macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported.
+
+## Full Documentation
+
+See [INSTALL.md](INSTALL.md) for complete usage, flags, environment variables,
+and troubleshooting.
+
+## License
+
+Business Source License 1.1 -- Labyrinth Analytics Consulting

loreconvo_cli-0.1.0a1/loreconvo_cli.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+loreconvo_cli/__init__.py
+loreconvo_cli/_db_path.py
+loreconvo_cli/_platform_check.py
+loreconvo_cli/_schema_compat.py
+loreconvo_cli/_write_guard.py
+loreconvo_cli/main.py
+loreconvo_cli.egg-info/PKG-INFO
+loreconvo_cli.egg-info/SOURCES.txt
+loreconvo_cli.egg-info/dependency_links.txt
+loreconvo_cli.egg-info/entry_points.txt
+loreconvo_cli.egg-info/requires.txt
+loreconvo_cli.egg-info/top_level.txt
+tests/test_cli.py

loreconvo_cli-0.1.0a1/loreconvo_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

loreconvo_cli-0.1.0a1/loreconvo_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loreconvo-cli = loreconvo_cli.main:main

loreconvo_cli-0.1.0a1/loreconvo_cli.egg-info/requires.txt

@@ -0,0 +1,7 @@
+typer==0.13.1
+
+[dev]
+pytest==8.3.4
+
+[server]
+loreconvo==0.7.1

loreconvo_cli-0.1.0a1/loreconvo_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+loreconvo_cli

loreconvo_cli-0.1.0a1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "loreconvo-cli"
+version = "0.1.0a1"
+description = "Command-line interface for LoreConvo cross-surface session memory"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Labyrinth Analytics Consulting" }
+]
+keywords = ["mcp", "claude", "memory", "cli", "sessions", "ai-tools", "claude-plugin"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+]
+
+dependencies = [
+    "typer==0.13.1",
+]
+
+[project.optional-dependencies]
+server = [
+    "loreconvo==0.7.1",  # allow-range: loreconvo -- CLI depends on server for write ops
+]
+dev = [
+    "pytest==8.3.4",
+]
+
+[project.scripts]
+loreconvo-cli = "loreconvo_cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/labyrinth-analytics/loreconvo-cli"
+Repository = "https://github.com/labyrinth-analytics/loreconvo-cli"
+"Bug Tracker" = "https://github.com/labyrinth-analytics/loreconvo-cli/issues"
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"

loreconvo_cli-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loreconvo_cli-0.1.0a1/tests/test_cli.py

@@ -0,0 +1,241 @@
+"""Tests for loreconvo-cli."""
+
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+import pytest
+
+# Ensure the package is importable from this test directory
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+@pytest.fixture
+def tmp_db(tmp_path):
+    """Create a minimal loreconvo sessions.db fixture."""
+    db_path = tmp_path / "sessions.db"
+    conn = sqlite3.connect(str(db_path))
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.executescript("""
+        CREATE TABLE sessions (
+            id TEXT PRIMARY KEY NOT NULL,
+            title TEXT NOT NULL,
+            surface TEXT NOT NULL,
+            project TEXT,
+            start_date TEXT NOT NULL,
+            summary TEXT,
+            decisions TEXT,
+            open_questions TEXT,
+            tags TEXT
+        );
+        INSERT INTO sessions VALUES
+            ('abc-123', 'Test session 1', 'code', 'side_hustle',
+             '2026-05-30T01:00:00Z', 'Summary of session 1',
+             '["decision A", "decision B"]', '["question 1"]', '["tag1"]'),
+            ('def-456', 'Another session', 'chat', NULL,
+             '2026-05-29T10:00:00Z', 'Another summary', NULL, NULL, NULL);
+        CREATE VIRTUAL TABLE sessions_fts USING fts5(
+            id,
+            title,
+            summary,
+            content='sessions',
+            content_rowid='rowid'
+        );
+    """)
+    conn.commit()
+    conn.close()
+    return db_path
+
+
+def test_open_db_missing(tmp_path, capsys):
+    """open_db exits with code 1 and helpful message when DB not found."""
+    from loreconvo_cli._db_path import open_db
+
+    missing = tmp_path / "missing.db"
+    with pytest.raises(SystemExit) as exc:
+        open_db(missing)
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "not found" in captured.err
+    assert "pip install loreconvo-cli[server]" in captured.err
+
+
+def test_open_db_exists(tmp_db):
+    """open_db returns a live connection for a valid DB."""
+    from loreconvo_cli._db_path import open_db
+
+    conn = open_db(tmp_db)
+    assert conn is not None
+    row = conn.execute("SELECT COUNT(*) FROM sessions").fetchone()
+    assert row[0] == 2
+    conn.close()
+
+
+def test_sanitize_fts5():
+    """FTS5 injection chars are stripped."""
+    from loreconvo_cli._db_path import _sanitize_fts5
+
+    assert '"' not in _sanitize_fts5('hello "world"')
+    assert "*" not in _sanitize_fts5("foo*")
+    assert "^" not in _sanitize_fts5("^bar")
+    assert _sanitize_fts5("   ") == '""'
+    assert _sanitize_fts5("normal query") == "normal query"
+
+
+def test_schema_compat_normal(tmp_db):
+    """schema compat returns 'normal' for unversioned DB (user_version=0)."""
+    from loreconvo_cli._db_path import open_db
+    from loreconvo_cli._schema_compat import check_schema_compatibility
+
+    conn = open_db(tmp_db)
+    result = check_schema_compatibility(conn)
+    assert result == "normal"
+    conn.close()
+
+
+def test_schema_compat_too_new(tmp_db, capsys):
+    """schema compat exits when user_version exceeds max read version."""
+    from loreconvo_cli._db_path import open_db
+    from loreconvo_cli._schema_compat import CLI_MAX_READ_VERSION, check_schema_compatibility
+
+    conn = sqlite3.connect(str(tmp_db))
+    conn.execute(f"PRAGMA user_version = {CLI_MAX_READ_VERSION + 1}")
+    conn.commit()
+    conn.close()
+
+    conn = open_db(tmp_db)
+    with pytest.raises(SystemExit) as exc:
+        check_schema_compatibility(conn)
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "newer than loreconvo-cli supports" in captured.err
+
+
+def test_write_guard_blocks_without_server(monkeypatch):
+    """require_write_capability exits when server package not installed."""
+    from loreconvo_cli._write_guard import _has_server_package, require_write_capability
+
+    monkeypatch.setattr(
+        "loreconvo_cli._write_guard._has_server_package", lambda: False
+    )
+    with pytest.raises(SystemExit) as exc:
+        require_write_capability("save")
+    assert exc.value.code == 1
+
+
+def test_write_guard_passes_with_server(monkeypatch):
+    """require_write_capability does not exit when server package is installed."""
+    from loreconvo_cli._write_guard import require_write_capability
+
+    monkeypatch.setattr(
+        "loreconvo_cli._write_guard._has_server_package", lambda: True
+    )
+    require_write_capability("save")  # should not raise
+
+
+def test_get_db_path_default():
+    """get_db_path returns the default path when no arg or env var."""
+    from loreconvo_cli._db_path import DEFAULT_DB_PATH, get_db_path
+
+    env_backup = os.environ.pop("LORECONVO_DB_PATH", None)
+    try:
+        result = get_db_path(None)
+        assert result == DEFAULT_DB_PATH
+    finally:
+        if env_backup is not None:
+            os.environ["LORECONVO_DB_PATH"] = env_backup
+
+
+def test_platform_check_linux_x86(monkeypatch):
+    """check_platform passes on linux x86_64."""
+    import platform as _platform
+
+    monkeypatch.setattr(sys, "platform", "linux")
+    monkeypatch.setattr(_platform, "machine", lambda: "x86_64")
+    from loreconvo_cli._platform_check import check_platform
+
+    check_platform()  # should not raise
+
+
+def test_platform_check_windows(monkeypatch, capsys):
+    """check_platform exits on Windows."""
+    import platform as _platform
+
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setattr(_platform, "machine", lambda: "AMD64")
+    from loreconvo_cli._platform_check import check_platform
+
+    with pytest.raises(SystemExit) as exc:
+        check_platform()
+    assert exc.value.code == 1
+    assert "not supported" in capsys.readouterr().err
+
+
+def test_list_sessions_reads_db(tmp_db, monkeypatch):
+    """list command reads sessions from a real DB via the typer runner."""
+    from typer.testing import CliRunner
+    from loreconvo_cli.main import app
+
+    monkeypatch.setenv("LORECONVO_DB_PATH", str(tmp_db))
+    monkeypatch.setenv("LORECONVO_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loreconvo_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["list", "--limit", "5"])
+    assert result.exit_code == 0, result.output + str(result.exception)
+    assert "Test session 1" in result.output
+    assert "abc-123" in result.output
+
+
+def test_search_sessions(tmp_db, monkeypatch):
+    """search command returns sessions matching the query."""
+    from typer.testing import CliRunner
+    from loreconvo_cli.main import app
+
+    monkeypatch.setenv("LORECONVO_DB_PATH", str(tmp_db))
+    monkeypatch.setenv("LORECONVO_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loreconvo_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["search", "Test"])
+    assert result.exit_code == 0, result.output + str(result.exception)
+    assert "Test session 1" in result.output
+
+
+def test_read_by_id(tmp_db, monkeypatch):
+    """read --id returns the session detail."""
+    from typer.testing import CliRunner
+    from loreconvo_cli.main import app
+
+    monkeypatch.setenv("LORECONVO_DB_PATH", str(tmp_db))
+    monkeypatch.setenv("LORECONVO_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loreconvo_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["read", "--id", "abc-123"])
+    assert result.exit_code == 0, result.output + str(result.exception)
+    assert "Test session 1" in result.output
+    assert "decision A" in result.output
+
+
+def test_save_blocked_without_server(tmp_db, monkeypatch):
+    """save command exits 1 without server package."""
+    from typer.testing import CliRunner
+    from loreconvo_cli.main import app
+
+    monkeypatch.setenv("LORECONVO_DB_PATH", str(tmp_db))
+    monkeypatch.setenv("LORECONVO_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loreconvo_cli.main.check_platform", lambda: None)
+    monkeypatch.setattr(
+        "loreconvo_cli._write_guard._has_server_package", lambda: False
+    )
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        ["save", "--title", "t", "--surface", "code", "--summary", "s"],
+        catch_exceptions=False,
+    )
+    assert result.exit_code == 1