agemem 0.1.0__py3-none-any.whl

agemem/LICENSE.raw-rag

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

agemem/RAW_RAG_ATTRIBUTION.md

@@ -0,0 +1,22 @@
+# RAW-RAG attribution
+
+`raw_rag.py` adapts the overlapping token-window algorithm and dense candidate /
+reranking pipeline from RAW-RAG, MIT License, copyright 2026 RAW-RAG contributors.
+Full upstream license: `LICENSE.raw-rag`, included in this package.
+
+Upstream: https://github.com/Litmeb/RAW-RAG
+Revision: `95639191e9547219b426710e50fe1a36235e26fc`
+Reference: `methods/EverCore/evaluation/src/adapters/rag_adapter.py`
+Reference file SHA256: `997c35db93feea77eed897b3d5640bd9cd6f114da40bff5128efae65a6466637`
+
+This is a deliberate adaptation, not an upstream reproduction. Source records
+are chunked separately (256 cl100k tokens, overlap32), with exact source IDs.
+The original conversation headers, cross-turn windows, temporal filters,
+remote embedding/reranking/answer clients, incremental conversation ingestion,
+dynamic selection and optional PostgreSQL support are omitted. Agemem filters
+project, branch and current snapshot visibility before calling this adapter.
+BGE/MiniLM run locally; dense cosine top128 feeds rerank top15, followed by
+Agemem's context budget. Model licenses remain separate from source licensing.
+
+The live service uses only this adapted implementation; no upstream checkout or
+comparison harness is required.

agemem/__init__.py

@@ -0,0 +1,2 @@
+"""Live project memory composed from a memory bank, jev-mem and source retrieval."""
+__version__ = "0.1.0"

agemem/cli.py

@@ -0,0 +1,129 @@
+"""User-facing project setup and live memory commands."""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .engine import Engine
+from .project import initialize
+from .config import initialize_user_config, doctor, provider_options
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd(), help="Project checkout to use")
+    parser.add_argument("--offline", action="store_true", help="Never use hosted decisions or download embedding weights")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("project", help="Set up a project and its MCP connection")
+    project_init = p.add_subparsers(dest="project_command", required=True).add_parser("init", help="Ensure user config, project files, index and MCP registration")
+    clients = project_init.add_mutually_exclusive_group()
+    clients.add_argument("--client", choices=["codex", "cursor", "claude-code"], help="Register one client")
+    clients.add_argument("--mcp", nargs="+", choices=["codex", "cursor", "claude", "claude-code"], help="Register selected clients; claude means Claude Code")
+    project_init.add_argument("--model", choices=["jev", "qsiv"], help="Select the decision provider without prompting")
+    hook_options = project_init.add_mutually_exclusive_group()
+    hook_options.add_argument("--no-hooks", dest="hooks", action="store_false", help="Do not install lifecycle hooks")
+    hook_options.add_argument("--hooks", dest="hooks", action="store_true", help=argparse.SUPPRESS)
+    project_init.set_defaults(hooks=True)
+    project_init.add_argument("--executable", type=Path, help="Use an installed agemem executable instead of uvx (source testing)")
+    project_init.add_argument("--no-input", action="store_true", help="Never prompt; fail when required setup choices are missing")
+    project_init.add_argument("--retrieval", choices=["hybrid", "bm25", "raw-rag"], default="hybrid")
+    project_init.add_argument("--embedder", default="BAAI/bge-small-en-v1.5")
+    p = sub.add_parser("config", help="Manage user configuration")
+    p.add_subparsers(dest="config_command", required=True).add_parser("init", help="Create a private YAML template without overwriting existing settings")
+    p = sub.add_parser("provider", help="Set up optional local providers")
+    provider_sub = p.add_subparsers(dest="provider_command", required=True)
+    setup = provider_sub.add_parser("setup", help="Explicitly download models and install an isolated runtime")
+    setup.add_argument("provider_name", choices=["qsiv"])
+    setup.add_argument("--model-directory", type=Path)
+    setup.add_argument("--runtime-directory", type=Path)
+    setup.add_argument("--dry-run", action="store_true", help="Show actions without downloads or filesystem changes")
+    sub.add_parser("doctor", help="Check provider setup without inference or API calls")
+    p = sub.add_parser("init", help="Create missing bank/config files; preserve existing memory")
+    p.add_argument("--retrieval", choices=["hybrid", "bm25", "raw-rag"], default="hybrid")
+    p.add_argument("--embedder", default="BAAI/bge-small-en-v1.5")
+    sub.add_parser("index", help="Snapshot selected tracked project files; no hosted calls")
+    p = sub.add_parser("capture", help="Archive original text as untrusted source evidence")
+    p.add_argument("text")
+    p.add_argument("--label", default="event")
+    p.add_argument("--shared", action="store_true")
+    p = sub.add_parser("remember", help="Write a durable note through jev-mem's actual screens")
+    p.add_argument("text")
+    p.add_argument("--source-id")
+    p.add_argument("--shared", action="store_true")
+    p = sub.add_parser("recall", help="Read current bank, recall notes, and retrieve source evidence live")
+    p.add_argument("query")
+    p.add_argument("--budget", type=int)
+    p.add_argument("--history", action="store_true", help="Also search older file snapshots on this branch")
+    sub.add_parser("maintain", help="Screen pending notes and run jev-mem consolidation")
+    sub.add_parser("mcp", help="Run the project's MCP server over stdio")
+    p = sub.add_parser("mcp-install", help="Register this project with a coding client")
+    p.add_argument("--client", choices=["codex", "cursor", "claude-code"], help="Prompt when omitted")
+    p.add_argument("--dry-run", action="store_true", help="Preview registration without changing client configuration")
+    p.add_argument("--executable", type=Path, help="Use an installed agemem executable instead of uvx")
+    p = sub.add_parser("hooks-install", help="Install optional read-only lifecycle hooks")
+    p.add_argument("--client", nargs="+", choices=["codex", "claude", "claude-code"], required=True)
+    p.add_argument("--executable", type=Path)
+    p.add_argument("--dry-run", action="store_true")
+    p = sub.add_parser("hook", help="Handle client lifecycle JSON on stdin; local read-only context")
+    p.add_argument("event", choices=["session-start", "user-prompt"])
+    args = parser.parse_args()
+    try:
+        if args.command == "project":
+            from .setup import initialize_project
+            result = initialize_project(args.project, args.client, args.retrieval, args.embedder, args.offline, model=args.model, clients=args.mcp, no_input=args.no_input, hooks=args.hooks, executable=args.executable)
+        elif args.command == "config":
+            result = initialize_user_config()
+        elif args.command == "mcp-install":
+            from .mcp_install import install
+            result = install(args.project, args.client, args.dry_run, args.offline, args.executable)
+        elif args.command == "hooks-install":
+            from .hooks import install
+            result = install(args.project, args.client, args.executable, args.dry_run)
+        elif args.command == "hook":
+            from .hooks import run
+            run(args.project, args.event)
+            return
+        elif args.command == "provider":
+            from .providers import setup_qsiv
+            options = provider_options({})
+            if options["qsiv_runtime"] != "fp8":
+                raise ValueError("Automatic QSIV setup currently supports runtime fp8 only")
+            runtime_python = options.get("qsiv_python")
+            runtime_directory = args.runtime_directory or (Path(runtime_python).parent.parent if runtime_python else None)
+            result = setup_qsiv(directory=args.model_directory or options.get("qsiv_directory"),
+                                runtime_directory=runtime_directory, dry_run=args.dry_run)
+        elif args.command == "doctor":
+            result = doctor(args.project)
+        elif args.command == "init":
+            result = initialize(args.project, args.retrieval, args.embedder)
+        elif args.command == "mcp":
+            from .mcp import serve
+            serve(args.project, args.offline)
+            return
+        else:
+            engine = Engine(args.project, args.offline)
+            try:
+                if args.command == "index":
+                    result = engine.index()
+                elif args.command == "capture":
+                    result = engine.capture(args.text, args.label, args.shared)
+                elif args.command == "remember":
+                    result = engine.remember(args.text, args.source_id, args.shared)
+                elif args.command == "recall":
+                    result = engine.recall(args.query, args.budget, args.history)
+                else:
+                    result = engine.maintain()
+            finally:
+                engine.close()
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        if args.command == "doctor" and not result["ok"]:
+            raise SystemExit(1)
+    except Exception as exc:
+        # Do not echo SDK exception bodies, key-bearing URLs or supplied source text.
+        message = str(exc) if isinstance(exc, ValueError) else "See installation/runtime diagnostics; provider details omitted"
+        print(json.dumps({"error": type(exc).__name__, "message": message}), file=sys.stderr)
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main()

agemem/config.py

@@ -0,0 +1,133 @@
+"""User configuration, kept outside project checkouts and never written implicitly."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+CONFIG_VERSION = 1
+
+PROVIDERS = ("jev", "qsiv", "ollaya", "cascade")
+
+
+def config_path():
+    explicit = os.environ.get("AGEMEM_CONFIG")
+    return Path(explicit).expanduser() if explicit else Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))) / "agemem/config.yaml"
+
+
+def load_user_config():
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text())
+        if data is None:
+            data = {}
+    except yaml.YAMLError:
+        raise ValueError("Invalid YAML in agemem user configuration") from None
+    if not isinstance(data, dict):
+        raise ValueError("Agemem user configuration must be a YAML mapping")
+    version = data.get("version", CONFIG_VERSION)
+    if type(version) is not int or version != CONFIG_VERSION:
+        raise ValueError("Unsupported config.yaml version; this release supports version: 1. Use a compatible Agemem release or migrate the configuration")
+    if data.get("default_provider", "jev") not in PROVIDERS:
+        raise ValueError("Unsupported default_provider in agemem user configuration")
+    providers = data.get("providers", {})
+    if not isinstance(providers, dict) or any(not isinstance(value, dict) for value in providers.values()):
+        raise ValueError("providers must map provider names to option mappings")
+    return data
+
+
+def provider_options(project):
+    user = load_user_config()
+    providers = user.get("providers", {})
+    qsiv = providers.get("qsiv", {})
+    jev = providers.get("jev", {})
+    backend = os.environ.get("AGEMEM_PROVIDER") or project.get("decision_backend") or user.get("default_provider", "jev")
+    if backend not in PROVIDERS:
+        raise ValueError("Unsupported decision backend")
+    runtime = project.get("qsiv_runtime", qsiv.get("runtime", "fp8"))
+    if runtime not in ("fp8", "reference"):
+        raise ValueError("qsiv runtime must be fp8 or reference")
+    directory = os.environ.get("AGEMEM_QSIV_DIR") or project.get("qsiv_directory") or qsiv.get("model_directory")
+    if directory is not None and not isinstance(directory, str):
+        raise ValueError("QSIV model_directory must be a path string")
+    key = os.environ.get("AGEMEM_JEV_API_KEY") or os.environ.get("TYPESAFE_API_KEY") or os.environ.get("JEV_API_KEY") or jev.get("api_key")
+    if key is not None and not isinstance(key, str):
+        raise ValueError("Jev api_key must be a string")
+    data_root = Path(os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local/share")))
+    directory = directory or str(data_root / "agemem/models/qsiv")
+    default_python = data_root / "agemem/runtimes/qsiv/bin/python"
+    runtime_python = os.environ.get("AGEMEM_QSIV_PYTHON") or qsiv.get("python")
+    if runtime_python is not None and not isinstance(runtime_python, str):
+        raise ValueError("QSIV python must be a path string")
+    if runtime_python is None and default_python.is_file():
+        runtime_python = str(default_python)
+    return {"decision_backend": backend, "qsiv_python": str(Path(runtime_python).expanduser()) if runtime_python else None, "qsiv_runtime": runtime,
+            "qsiv_directory": str(Path(directory).expanduser()) if directory else None,
+            "jev_api_key": key}
+
+
+def initialize_user_config(default_provider="jev", api_key=None):
+    if default_provider not in PROVIDERS:
+        raise ValueError("Unsupported default provider")
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data_root = Path(os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local/share")))
+    template = """# Configuration schema version (independent of the Agemem package version).
+version: 1
+# Provider selection is global; projects can explicitly override it.
+# Options: jev, qsiv, cascade (or ollaya for the local Ollaya backend).
+default_provider: jev
+providers:
+  jev:
+    # Prefer AGEMEM_JEV_API_KEY, TYPESAFE_API_KEY or JEV_API_KEY.
+    api_key: null
+  qsiv:
+    runtime: fp8
+    model_directory: MODEL_DIRECTORY
+    # python: ~/.local/share/agemem/runtimes/qsiv/bin/python
+"""
+    template = template.replace("default_provider: jev", "default_provider: " + default_provider)
+    if api_key is not None:
+        template = template.replace("api_key: null", "api_key: " + yaml.safe_dump(api_key, default_style='"').strip())
+    template = template.replace("MODEL_DIRECTORY", yaml.safe_dump(str(data_root / "agemem/models/qsiv"), default_style='"').strip())
+    try:
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        return {"path": str(path), "created": False}
+    with os.fdopen(descriptor, "w") as stream:
+        stream.write(template)
+    return {"path": str(path), "created": True}
+
+
+def doctor(project):
+    """Inspect configuration without opening stores, downloading or calling providers."""
+    from .project import configuration
+    path = Path(project).expanduser().resolve()
+    options = configuration(path) if (path / ".agemem/config.json").exists() else provider_options({})
+    backend = options["decision_backend"]
+    checks = {"user_config": str(config_path()), "user_config_exists": config_path().exists(),
+              "provider": backend, "project_initialized": (path / ".agemem/config.json").exists()}
+    issues = []
+    if backend in ("jev", "cascade"):
+        checks["jev_credentials_present"] = bool(options.get("jev_api_key"))
+        if not checks["jev_credentials_present"]:
+            issues.append("Set a Jev API key in the user configuration or environment")
+    if backend in ("qsiv", "cascade"):
+        directory = options.get("qsiv_directory")
+        checks["qsiv_model_directory"] = directory
+        checks["qsiv_model_directory_exists"] = bool(directory and Path(directory).is_dir())
+        if not checks["qsiv_model_directory_exists"]:
+            issues.append("Configure and install the QSIV model directory")
+        from .providers import qsiv_doctor
+        import sys
+        runtime_python = options.get("qsiv_python") or sys.executable
+        runtime_directory = Path(runtime_python).parent.parent if runtime_python else None
+        diagnostic = qsiv_doctor(directory=directory, runtime_directory=runtime_directory, runtime_python=runtime_python, runtime=options["qsiv_runtime"])
+        checks["qsiv"] = diagnostic
+        if not diagnostic.get("ready", False):
+            issues.append("QSIV runtime diagnostics require attention; see checks.qsiv")
+    return {"ok": not issues, "checks": checks, "issues": issues,
+            "note": "Read-only diagnostics; no model inference or API calls performed"}

agemem/data/qsiv-linux-py312.lock

@@ -0,0 +1,90 @@
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.15.1
+attrs==26.1.0
+certifi==2026.10.23
+cffi==2.1.1
+charset-normalizer==3.5.2
+click==8.5.0
+cryptography==50.0.2
+cuda-bindings==13.4.4
+cuda-pathfinder==1.8.4
+cuda-toolkit==13.0.2
+fastembed==0.9.1
+filelock==4.2.4
+flatbuffers==25.12.19
+fsspec==2026.9.0
+h11==0.16.0
+hf-xet==1.7.0
+httpcore==1.0.9
+httpcore2==2.16.0
+httpx==0.28.1
+httpx2==2.16.0
+huggingface-hub==1.33.0
+idna==3.20
+jinja2==3.1.6
+jsonschema==4.26.0
+jsonschema-specifications==2025.9.1
+loguru==0.7.3
+markdown-it-py==4.2.0
+markupsafe==3.0.4
+mcp==2.3.0
+mcp-types==2.3.0
+mdurl==0.1.2
+mmh3==5.3.1
+mpmath==1.3.0
+networkx==3.7
+numpy==2.5.4
+nvidia-cublas==13.1.0.3
+nvidia-cuda-cupti==13.0.85
+nvidia-cuda-nvrtc==13.0.88
+nvidia-cuda-runtime==13.0.96
+nvidia-cudnn-cu13==9.19.0.56
+nvidia-cufft==12.0.0.61
+nvidia-cufile==1.15.1.6
+nvidia-curand==10.4.0.35
+nvidia-cusolver==12.0.4.66
+nvidia-cusparse==12.6.3.3
+nvidia-cusparselt-cu13==0.8.0
+nvidia-nccl-cu13==2.28.9
+nvidia-nvjitlink==13.0.88
+nvidia-nvshmem-cu13==3.4.5
+nvidia-nvtx==13.0.85
+onnxruntime==1.31.0
+opentelemetry-api==1.45.1
+packaging==26.3
+pillow==13.0.0
+protobuf==7.36.2
+py-rust-stemmers==0.1.8
+pycparser==3.12
+pydantic==2.14.1
+pydantic-core==2.50.1
+pygments==2.21.0
+pyjwt==2.15.1
+python-multipart==0.0.32
+pyyaml==6.0.3
+referencing==0.37.0
+regex==2026.9.29
+requests==2.34.2
+rich==15.0.0
+rpds-py==2026.9.1
+safetensors==0.8.0
+setuptools==81.0.0
+shellingham==1.5.4
+sqlite-vec==0.1.9
+sse-starlette==3.6.0
+starlette==1.10.0
+sympy==1.14.0
+tenacity==9.2.1
+tokenizers==0.22.2
+torch==2.11.0
+tqdm==4.70.1
+transformers==5.14.1
+triton==3.6.0
+truststore==0.10.5
+typer==0.27.3
+typesafe-sdk==0.7.5
+typing-extensions==4.16.0
+typing-inspection==0.4.4
+urllib3==2.8.0
+uvicorn==0.54.0