memty 0.1.0__py3-none-any.whl

memoryport/__init__.py

@@ -0,0 +1,20 @@
+"""Internal implementation modules for the Memty SDK."""
+
+from .memory import MongoSyncedMemoryStore, PortableMemoryStore
+from .router import ModelSpec, RouteDecision, SmartRouter
+from .ledger import MemoryLedger
+from .evaluation import evaluate_cases
+from .vault import export_nxvault, import_nxvault
+from .mongo_ledger import MongoMemoryLedger
+from .extractor import MemoryExtractor
+from .sdk import ChatResponse, Memty, RouteResult, ModelConfig, load_client
+NexorAI = Memty  # Keep the former Python name as a compatibility alias.
+from .embeddings import (EmbeddingAdapter, EmbeddingConfig, EmbeddingError,
+                         GeminiEmbeddingAdapter, OpenAICompatibleEmbeddingAdapter)
+
+__all__ = ["ChatResponse", "EmbeddingAdapter", "EmbeddingConfig", "EmbeddingError", "GeminiEmbeddingAdapter",
+           "MemoryExtractor", "OpenAICompatibleEmbeddingAdapter",
+           "MemoryLedger", "ModelConfig", "ModelSpec", "MongoMemoryLedger",
+           "MongoSyncedMemoryStore", "Memty", "NexorAI", "PortableMemoryStore", "RouteDecision", "RouteResult",
+           "SmartRouter", "evaluate_cases", "export_nxvault", "import_nxvault", "load_client"]
+

memoryport/api.py

@@ -0,0 +1,198 @@
+"""Loopback-only HTTP API for the local memory vault.
+
+This API is intended for a local UI or trusted desktop bridge. External agents
+should use the approval-only MCP interface instead of receiving write access.
+"""
+
+from __future__ import annotations
+
+import hmac
+import os
+import contextvars
+import hashlib
+from pathlib import Path
+import re
+from typing import Any
+
+from .factory import open_ledger
+from .ledger import MemoryLedger
+from .extractor import MemoryExtractor
+
+try:
+    from fastapi import Depends, FastAPI, Header, HTTPException
+    from fastapi.responses import Response
+except ImportError as error:
+    raise RuntimeError("HTTP API support requires: pip install 'memty[server]'") from error
+
+
+_request_user: contextvars.ContextVar[str] = contextvars.ContextVar("memty_vault_user", default="local")
+
+
+def _ledger() -> MemoryLedger:
+    return open_ledger(_request_user.get())
+
+
+async def _authorized(authorization: str | None = Header(default=None),
+                      x_memty_user: str | None = Header(default=None),
+                      x_nexor_user: str | None = Header(default=None)) -> None:
+    secret = os.getenv("MEMTY_VAULT_API_TOKEN") or os.getenv("NEXOR_VAULT_API_TOKEN", "")
+    if len(secret) < 32:
+        raise HTTPException(503, "Configure a random MEMTY_VAULT_API_TOKEN of at least 32 characters.")
+    supplied = authorization.removeprefix("Bearer ") if authorization else ""
+    if not hmac.compare_digest(supplied.encode(), secret.encode()):
+        raise HTTPException(401, "Invalid local vault token.")
+    multi_user = os.getenv("MEMTY_VAULT_MULTIUSER", os.getenv("NEXOR_VAULT_MULTIUSER", "false")).casefold() == "true"
+    user_id = x_memty_user or x_nexor_user
+    if multi_user and not user_id:
+        raise HTTPException(400, "X-Memty-User is required in multi-user mode.")
+    if user_id:
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,200}", user_id):
+            raise HTTPException(400, "Invalid vault user identifier.")
+        if not multi_user:
+            raise HTTPException(403, "Multi-user mode is disabled.")
+        _request_user.set(user_id)
+    else:
+        _request_user.set(os.getenv("MEMTY_VAULT_USER", os.getenv("NEXOR_VAULT_USER", "local")))
+
+
+app = FastAPI(title="Memty Memory Vault", version="1.0.0", dependencies=[Depends(_authorized)])
+
+
+@app.get("/v1/health")
+def health() -> dict[str, str]:
+    return {"status": "ok", "format": MemoryLedger.FORMAT}
+
+
+@app.get("/v1/memories")
+def list_memories(history: bool = False, status: str | None = None) -> list[dict[str, Any]]:
+    records = _ledger().list(include_history=history)
+    newer = {record.get("supersedes_id"): record["id"] for record in records if record.get("supersedes_id")}
+    for record in records:
+        if record["status"] == "SUPERSEDED":
+            record["superseded_by_id"] = newer.get(record["id"])
+    if status:
+        records = [record for record in records if record["status"] == status.upper()]
+    return records
+
+
+@app.post("/v1/memories")
+def create_memory(payload: dict[str, Any]) -> dict[str, Any]:
+    try:
+        return _ledger().record(
+            payload.get("namespace", "personal.general"), payload["slot_key"], payload["value"],
+            confidence=1.0, verification_state="USER_CONFIRMED",
+            sensitivity_tier=payload.get("sensitivity_tier", "PERSONAL"),
+            allowed_providers=payload.get("allowed_providers"),
+            blocked_providers=payload.get("blocked_providers"),
+            ephemeral_redaction=bool(payload.get("ephemeral_redaction", False)),
+            source_conversation_id=payload.get("source_conversation_id"),
+            source_message=payload.get("source_message"),
+        )
+    except (KeyError, TypeError, ValueError) as error:
+        raise HTTPException(400, str(error)) from error
+
+
+@app.post("/v1/extract")
+def extract_memories(payload: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload.get("user_message"), str) or not isinstance(payload.get("memories"), list):
+        raise HTTPException(400, "user_message and a memories list are required.")
+    extractor = MemoryExtractor(_ledger(), lambda _prompt: {"memories": payload["memories"]})
+    try:
+        return extractor.ingest_turn(payload["user_message"], str(payload.get("assistant_response", "")),
+                                     conversation_id=payload.get("conversation_id"), model_id=payload.get("model_id"))
+    except (TypeError, ValueError) as error:
+        raise HTTPException(400, str(error)) from error
+
+
+@app.delete("/v1/memories/{memory_id}")
+def delete_memory(memory_id: str) -> dict[str, Any]:
+    result = _ledger().delete(memory_id)
+    if result is None:
+        raise HTTPException(404, "Memory not found.")
+    return result
+
+
+@app.patch("/v1/memories/{memory_id}")
+def edit_memory(memory_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    result = _ledger().edit(memory_id, value=payload.get("value"), pinned=payload.get("pinned"))
+    if result is None:
+        raise HTTPException(404, "Active memory not found.")
+    return result
+
+
+@app.post("/v1/context")
+def compile_context(payload: dict[str, Any]) -> dict[str, Any]:
+    try:
+        return _ledger().context(payload.get("query", ""), provider=payload["provider"],
+                                 token_budget=int(payload.get("token_budget", 900)),
+                                 as_of=payload.get("as_of"), namespace=payload.get("namespace"))
+    except (KeyError, TypeError, ValueError) as error:
+        raise HTTPException(400, str(error)) from error
+
+
+@app.get("/v1/memories/{namespace}/{slot_key}/as-of")
+def memory_as_of(namespace: str, slot_key: str, at: str, known_at: str | None = None) -> dict[str, Any] | None:
+    try:
+        return _ledger().as_of(namespace, slot_key, at, known_at=known_at)
+    except ValueError as error:
+        raise HTTPException(400, str(error)) from error
+
+
+@app.get("/v1/proposals")
+def list_proposals() -> list[dict[str, Any]]:
+    return _ledger().proposals()
+
+
+@app.post("/v1/proposals")
+def propose_memory(payload: dict[str, Any]) -> dict[str, str]:
+    try:
+        policy = payload.get("policy") or {}
+        proposal_id = _ledger().propose(payload["namespace"], payload["slot_key"], payload["value"], **policy)
+        return {"proposal_id": proposal_id, "status": "PENDING_CONFIRMATION"}
+    except (KeyError, TypeError, ValueError) as error:
+        raise HTTPException(400, str(error)) from error
+
+
+@app.post("/v1/proposals/{proposal_id}/approve")
+def approve_proposal(proposal_id: str) -> dict[str, Any]:
+    result = _ledger().resolve_proposal(proposal_id, approve=True)
+    if result is None:
+        raise HTTPException(404, "Proposal not found or already resolved.")
+    return result
+
+
+@app.post("/v1/proposals/{proposal_id}/reject")
+def reject_proposal(proposal_id: str) -> dict[str, Any]:
+    result = _ledger().resolve_proposal(proposal_id, approve=False)
+    if result is None:
+        raise HTTPException(404, "Proposal not found or already resolved.")
+    return result
+
+
+@app.post("/v1/vault/export")
+def export_vault(payload: dict[str, Any]) -> Response:
+    from .vault import encode_nxvault
+    try:
+        bundle = encode_nxvault(_ledger(), passphrase=payload["passphrase"])
+    except (KeyError, TypeError, ValueError, RuntimeError) as error:
+        raise HTTPException(400, str(error)) from error
+    return Response(bundle, media_type="application/vnd.nexor.nxvault",
+                    headers={"Content-Disposition": "attachment; filename=memory.nxvault"})
+
+
+def main() -> None:
+    try:
+        import uvicorn
+    except ImportError as error:
+        raise RuntimeError("HTTP API support requires: pip install 'memty[server]'") from error
+    host = os.getenv("MEMTY_VAULT_API_HOST", os.getenv("NEXOR_VAULT_API_HOST", "127.0.0.1"))
+    allow_remote = os.getenv("MEMTY_VAULT_ALLOW_REMOTE", os.getenv("NEXOR_VAULT_ALLOW_REMOTE", "false"))
+    if host not in {"127.0.0.1", "localhost", "::1"} and allow_remote.casefold() != "true":
+        raise RuntimeError("Non-loopback binding requires MEMTY_VAULT_ALLOW_REMOTE=true and a strong API token.")
+    uvicorn.run("memty.api:app", host=host, port=int(os.getenv("MEMTY_VAULT_API_PORT", os.getenv("NEXOR_VAULT_API_PORT", "8765"))),
+                log_level="warning")
+
+
+if __name__ == "__main__":
+    main()
+

memoryport/cli.py

@@ -0,0 +1,94 @@
+"""Manage a local Memty temporal vault without a web account or model API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+from getpass import getpass
+
+from .factory import open_ledger
+from .factory import default_vault_path
+from .vault import export_nxvault, import_nxvault
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="memty vault")
+    parser.add_argument("--db", default=str(default_vault_path()))
+    parser.add_argument("--user", default=os.getenv("MEMTY_MEMORY_USER", os.getenv("NEXORAI_MEMORY_USER", os.getenv("MEMTY_VAULT_USER", os.getenv("NEXOR_VAULT_USER", "local")))))
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("list", help="list active and historical memories")
+    add = commands.add_parser("add", help="save a user-confirmed fact")
+    add.add_argument("namespace")
+    add.add_argument("slot_key")
+    add.add_argument("value")
+    add.add_argument("--sensitivity", default="PERSONAL")
+    add.add_argument("--allow-provider", action="append", default=[])
+    add.add_argument("--block-provider", action="append", default=[])
+    add.add_argument("--redact", action="store_true")
+    recall = commands.add_parser("context", help="compile provider-filtered context")
+    recall.add_argument("provider")
+    recall.add_argument("query")
+    recall.add_argument("--tokens", type=int, default=900)
+    remove = commands.add_parser("delete", help="forget a memory by id")
+    remove.add_argument("memory_id")
+    approve = commands.add_parser("approve", help="approve a pending proposal")
+    approve.add_argument("proposal_id")
+    reject = commands.add_parser("reject", help="reject a pending proposal")
+    reject.add_argument("proposal_id")
+    commands.add_parser("proposals", help="list pending proposals")
+    export = commands.add_parser("export", help="create a portable .nxvault file")
+    export.add_argument("path")
+    export.add_argument("--plaintext", action="store_true", help="allow an unencrypted export")
+    imp = commands.add_parser("import", help="import a .nxvault file")
+    imp.add_argument("path")
+    imp.add_argument("--replace", action="store_true", help="replace this vault's ledger")
+    evaluate = commands.add_parser("evaluate", help="run recall regression cases from a JSON file")
+    evaluate.add_argument("cases")
+    args = parser.parse_args()
+    ledger = open_ledger(args.user, path=args.db)
+
+    if args.command == "list":
+        print(json.dumps(ledger.list(include_history=True), ensure_ascii=False, indent=2))
+    elif args.command == "add":
+        result = ledger.record(args.namespace, args.slot_key, args.value,
+                               verification_state="USER_CONFIRMED", sensitivity_tier=args.sensitivity,
+                               allowed_providers=args.allow_provider, blocked_providers=args.block_provider,
+                               ephemeral_redaction=args.redact)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif args.command == "context":
+        print(json.dumps(ledger.context(args.query, provider=args.provider, token_budget=args.tokens),
+                         ensure_ascii=False, indent=2))
+    elif args.command == "delete":
+        result = ledger.delete(args.memory_id)
+        if result is None:
+            raise SystemExit("Memory not found or already deleted.")
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif args.command == "proposals":
+        print(json.dumps(ledger.proposals(), ensure_ascii=False, indent=2))
+    elif args.command in {"approve", "reject"}:
+        result = ledger.resolve_proposal(args.proposal_id, approve=args.command == "approve")
+        if result is None:
+            raise SystemExit("Proposal not found or already resolved.")
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif args.command == "export":
+        passphrase = None if args.plaintext else getpass("Vault passphrase (min 10 characters): ")
+        path = export_nxvault(ledger, args.path, passphrase=passphrase, allow_plaintext=args.plaintext)
+        print(path)
+    elif args.command == "import":
+        passphrase = getpass("Vault passphrase (leave empty for plaintext): ") or None
+        count = import_nxvault(ledger, args.path, passphrase=passphrase, merge=not args.replace)
+        print(f"Imported {count} ledger events.")
+    elif args.command == "evaluate":
+        from .evaluation import evaluate_cases
+        with open(args.cases, "r", encoding="utf-8") as handle:
+            cases = json.load(handle)
+        if not isinstance(cases, list):
+            raise SystemExit("Evaluation file must contain a JSON list of cases.")
+        print(json.dumps(evaluate_cases(ledger, cases), ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()
+

memoryport/embeddings.py

@@ -0,0 +1,130 @@
+"""Small standard-library embedding clients for portable semantic memory."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import re
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+
+class EmbeddingError(RuntimeError):
+    """An embedding provider could not return a usable vector."""
+
+
+@dataclass(frozen=True)
+class EmbeddingConfig:
+    provider: str = "openai-compatible"
+    model: str = "nomic-embed-text"
+    base_url: str = ""
+    api_key_env: str = ""
+    timeout_seconds: float = 20.0
+
+    def __post_init__(self) -> None:
+        if self.provider not in {"openai-compatible", "openrouter", "ollama", "lm-studio", "gemini"}:
+            raise ValueError("unsupported embedding provider")
+        if not re.fullmatch(r"[A-Za-z0-9._-]{1,128}", self.model) or not math.isfinite(self.timeout_seconds) or self.timeout_seconds <= 0:
+            raise ValueError("embedding model and timeout must be valid")
+        if self.api_key_env and not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", self.api_key_env):
+            raise ValueError("embedding api_key_env must be a valid environment variable name")
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "EmbeddingConfig":
+        accepted = {item.name for item in cls.__dataclass_fields__.values()}
+        return cls(**{key: item for key, item in value.items() if key in accepted})
+
+    @property
+    def cache_key(self) -> str:
+        identity = f"{self.provider}\0{self.model}\0{self.base_url.rstrip('/')}"
+        return f"{self.provider}:{self.model}:{hashlib.sha256(identity.encode()).hexdigest()[:16]}"
+
+
+class EmbeddingAdapter(Protocol):
+    def embed(self, text: str, config: EmbeddingConfig) -> list[float]: ...
+
+
+def _request(url: str, payload: dict[str, Any], headers: dict[str, str], timeout: float) -> dict[str, Any]:
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    request = Request(url, data=body, headers={"Content-Type": "application/json", **headers}, method="POST")
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            result = json.loads(response.read().decode("utf-8"))
+    except (HTTPError, URLError, TimeoutError, OSError, UnicodeDecodeError, json.JSONDecodeError):
+        raise EmbeddingError("Could not get an embedding from the configured provider.") from None
+    if not isinstance(result, dict):
+        raise EmbeddingError("Embedding provider returned an invalid response.")
+    return result
+
+
+def _base(config: EmbeddingConfig) -> str:
+    defaults = {
+        "openai-compatible": "https://api.openai.com/v1",
+        "openrouter": "https://openrouter.ai/api/v1",
+        "ollama": "http://localhost:11434/v1",
+        "lm-studio": "http://localhost:1234/v1",
+        "gemini": "https://generativelanguage.googleapis.com",
+    }
+    base = (config.base_url or defaults.get(config.provider, "")).rstrip("/")
+    parsed = urlparse(base)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise EmbeddingError("Embedding base_url must be an HTTP or HTTPS URL.")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise EmbeddingError("Use an environment variable for credentials; keep base_url free of query parameters.")
+    if parsed.scheme == "http" and parsed.hostname.lower() not in {"localhost", "127.0.0.1", "::1"}:
+        raise EmbeddingError("Use HTTPS for remote embedding providers; HTTP is allowed only on loopback.")
+    return base
+
+
+def _key(config: EmbeddingConfig) -> str:
+    key = os.getenv(config.api_key_env, "").strip() if config.api_key_env else ""
+    required = config.provider in {"gemini"}
+    if required and not key:
+        raise EmbeddingError(f"Set {config.api_key_env or 'api_key_env'} for the embedding provider.")
+    return key
+
+
+class OpenAICompatibleEmbeddingAdapter:
+    """OpenAI-compatible embeddings, including local Ollama and LM Studio."""
+
+    def embed(self, text: str, config: EmbeddingConfig) -> list[float]:
+        key = _key(config)
+        headers = {"Authorization": f"Bearer {key}"} if key else {}
+        response = _request(_base(config) + "/embeddings", {"model": config.model, "input": text},
+                            headers, config.timeout_seconds)
+        rows = response.get("data") or []
+        vector = rows[0].get("embedding") if rows and isinstance(rows[0], dict) else None
+        return _validate_vector(vector)
+
+
+class GeminiEmbeddingAdapter:
+    """Gemini embedContent endpoint with a separately configured embedding model."""
+
+    def embed(self, text: str, config: EmbeddingConfig) -> list[float]:
+        key = _key(config)
+        base = _base(config) if config.base_url else "https://generativelanguage.googleapis.com"
+        base = base.removesuffix("/v1beta").removesuffix("/v1")
+        endpoint = f"{base}/v1beta/models/{config.model}:embedContent"
+        response = _request(endpoint, {"content": {"parts": [{"text": text}]}},
+                            {"x-goog-api-key": key}, config.timeout_seconds)
+        vector = (response.get("embedding") or {}).get("values")
+        return _validate_vector(vector)
+
+
+def _validate_vector(value: Any) -> list[float]:
+    if not isinstance(value, list) or not value or len(value) > 32768:
+        raise EmbeddingError("Embedding provider returned no usable vector.")
+    try:
+        vector = [float(item) for item in value]
+    except (TypeError, ValueError):
+        raise EmbeddingError("Embedding provider returned an invalid vector.") from None
+    if not all(math.isfinite(item) for item in vector):
+        raise EmbeddingError("Embedding provider returned non-finite vector values.")
+    return vector
+
+

memoryport/evaluation.py

@@ -0,0 +1,57 @@
+"""Small deterministic evaluation harness for memory-state regressions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .ledger import MemoryLedger
+
+
+def evaluate_cases(ledger: MemoryLedger, cases: list[dict[str, Any]]) -> dict[str, Any]:
+    """Measure stale-value bleed, tombstone stickiness, and context density.
+
+    Each case has ``query``, ``provider`` and optional ``token_budget`` and
+    ``stale_values``. Set ``deleted_slot`` and ``deleted_value`` to probe the
+    explicit user-delete guard for a previously removed slot.
+    """
+    stale_denominator = stale_hits = sticky_denominator = sticky_passes = 0
+    fact_count = token_count = 0
+    details = []
+    for index, case in enumerate(cases):
+        compiled = ledger.context(str(case.get("query", "")),
+                                  provider=str(case.get("provider", "local")),
+                                  token_budget=int(case.get("token_budget", 900)),
+                                  as_of=case.get("as_of"))
+        text = compiled["text"].casefold()
+        stale = [str(value) for value in case.get("stale_values", []) if str(value)]
+        stale_denominator += bool(stale)
+        leaked = [value for value in stale if value.casefold() in text]
+        stale_hits += bool(leaked)
+        fact_count += len(compiled["citations"])
+        token_count += compiled["approx_tokens"]
+
+        sticky_result = None
+        if case.get("deleted_slot") and case.get("deleted_value"):
+            sticky_denominator += 1
+            state = ledger.slot_state(str(case["namespace"]), str(case["slot_key"]))
+            sticky_result = bool(state and state["status"] == "DELETED"
+                                 and str(case["deleted_value"]).casefold() not in text)
+            sticky_passes += sticky_result
+        details.append({"case": index, "stale_values_found": leaked,
+                        "context_facts": len(compiled["citations"]),
+                        "approx_tokens": compiled["approx_tokens"],
+                        "deleted_slot_blocked": sticky_result})
+
+    return {
+        "case_count": len(cases),
+        "stale_fact_bleed_rate": stale_hits / stale_denominator if stale_denominator else None,
+        "stale_fact_cases": stale_denominator,
+        "correction_stickiness_score": sticky_passes / sticky_denominator if sticky_denominator else None,
+        "deleted_slot_cases": sticky_denominator,
+        "token_density_facts_per_100_tokens": 100 * fact_count / token_count if token_count else 0.0,
+        "total_injected_facts": fact_count,
+        "approx_tokens": token_count,
+        "details": details,
+        "note": "Approximate token counts use 4 characters per token; compare only under the same tokenizer convention.",
+    }
+

memoryport/extractor.py

@@ -0,0 +1,94 @@
+"""Model-agnostic durable-fact extraction into canonical ledger slots."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Callable
+
+from .ledger import MemoryLedger
+
+
+_SECRET_LIKE = re.compile(
+    r"(?i)(?:\b(?:api[_ -]?key|password|secret|access[_ -]?token|private[_ -]?key)\b\s*(?:[:=]|is\s+)\s*\S+|"
+    r"\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16})\b)"
+)
+
+_INSTRUCTIONS = """Extract at most five durable facts that the user explicitly states in their message.
+Return only JSON in this schema:
+{"memories":[{"namespace":"work.project","slot_key":"primary_database","value":"MongoDB Atlas","confidence":0.9,"source_quote":"exact substring from the user message","sensitivity_tier":"PERSONAL","allowed_providers":[],"blocked_providers":[],"ephemeral_redaction":false,"valid_from":null}]}
+Use stable canonical namespace and slot keys. Return the same slot for a correction to an earlier value. Ignore questions, guesses, one-off tasks, secrets, credentials, and sensitive personal data. Do not derive facts from the assistant response. Keep values concise and factual. If nothing qualifies, return {"memories":[]}.
+"""
+
+
+class MemoryExtractor:
+    """Run a caller-supplied model function and validate its proposed memories.
+
+    ``generate_json`` receives a prompt and returns a JSON string or parsed
+    object. The vault itself never contacts a model provider.
+    """
+
+    def __init__(self, ledger: MemoryLedger, generate_json: Callable[[str], Any], *,
+                 minimum_confidence: float = 0.8, max_facts: int = 5):
+        if not 0 <= minimum_confidence <= 1:
+            raise ValueError("minimum_confidence must be between 0 and 1")
+        if not 1 <= max_facts <= 20:
+            raise ValueError("max_facts must be between 1 and 20")
+        self.ledger = ledger
+        self.generate_json = generate_json
+        self.minimum_confidence = minimum_confidence
+        self.max_facts = max_facts
+
+    def ingest_turn(self, user_message: str, assistant_response: str = "", *,
+                    conversation_id: str | None = None, model_id: str | None = None) -> dict[str, Any]:
+        user_message = str(user_message).strip()
+        if not user_message:
+            return {"saved": [], "skipped": 0}
+        prompt = (_INSTRUCTIONS + "\nUSER MESSAGE:\n" + user_message[:12000]
+                  + "\nASSISTANT RESPONSE (context only; do not extract facts from it):\n"
+                  + str(assistant_response)[:4000])
+        raw = self.generate_json(prompt)
+        parsed = json.loads(raw) if isinstance(raw, str) else raw
+        if not isinstance(parsed, dict) or not isinstance(parsed.get("memories", []), list):
+            raise ValueError("extractor must return a JSON object with a memories list")
+
+        saved = []
+        skipped = 0
+        user_folded = user_message.casefold()
+        for candidate in parsed.get("memories", [])[:self.max_facts]:
+            if not isinstance(candidate, dict):
+                skipped += 1
+                continue
+            quote = candidate.get("source_quote")
+            value = candidate.get("value")
+            try:
+                confidence = float(candidate.get("confidence", 0))
+            except (TypeError, ValueError):
+                skipped += 1
+                continue
+            if (not isinstance(quote, str) or not quote.strip() or quote.casefold() not in user_folded
+                or not isinstance(value, str) or not value.strip() or confidence < self.minimum_confidence
+                or _SECRET_LIKE.search(value) or _SECRET_LIKE.search(quote)):
+                skipped += 1
+                continue
+            tier = str(candidate.get("sensitivity_tier", "PERSONAL")).upper()
+            if tier in {"SECRET", "CONFIDENTIAL"}:
+                skipped += 1
+                continue
+            try:
+                record = self.ledger.record(
+                    str(candidate.get("namespace", "personal.general")), str(candidate.get("slot_key", "fact")),
+                    value, confidence=min(1.0, confidence), verification_state="AUTO_EXTRACTED",
+                    sensitivity_tier=tier,
+                    allowed_providers=candidate.get("allowed_providers") or [],
+                    blocked_providers=candidate.get("blocked_providers") or [],
+                    ephemeral_redaction=bool(candidate.get("ephemeral_redaction", False)),
+                    valid_from=candidate.get("valid_from"), source_conversation_id=conversation_id,
+                    source_message=quote.strip(), extracted_by_model=model_id,
+                )
+            except ValueError:
+                skipped += 1
+                continue
+            saved.append(record)
+        return {"saved": saved, "skipped": skipped}
+

memoryport/factory.py

@@ -0,0 +1,61 @@
+"""Create and cache the configured local or MongoDB ledger backend."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+import os
+from pathlib import Path
+
+from .ledger import MemoryLedger
+
+
+def default_vault_path() -> Path:
+    """Use Memty's data folder, reusing older vaults when they already exist."""
+    configured = (os.getenv("MEMTY_MEMORY_PATH") or os.getenv("MEMTY_VAULT_PATH")
+                  or os.getenv("NEXORAI_MEMORY_PATH") or os.getenv("NEXOR_VAULT_PATH"))
+    if configured:
+        return Path(configured).expanduser()
+    home = Path.home()
+    current = home / ".memty" / "memory.sqlite3"
+    previous = home / ".nexorai" / "memory.sqlite3"
+    legacy = home / ".nexor" / "memory.sqlite3"
+    if current.exists():
+        return current
+    if previous.exists():
+        return previous
+    if legacy.exists():
+        return legacy
+    return current
+
+
+@lru_cache(maxsize=512)
+def _sqlite(path: str, user_id: str) -> MemoryLedger:
+    return MemoryLedger(path, user_id=user_id)
+
+
+@lru_cache(maxsize=512)
+def _mongo(uri: str, database: str, collection: str, user_id: str):
+    from .mongo_ledger import MongoMemoryLedger
+    return MongoMemoryLedger(uri, user_id, database=database, collection=collection)
+
+
+def open_ledger(user_id: str = "local", *, path: str | Path | None = None):
+    """Open the selected backend, keeping one connection/store per user."""
+    backend = os.getenv("MEMTY_VAULT_BACKEND", os.getenv("NEXOR_VAULT_BACKEND", "sqlite")).casefold()
+    if backend == "mongodb":
+        uri = os.getenv("MEMTY_VAULT_MONGO_URI") or os.getenv("NEXOR_VAULT_MONGO_URI") or os.getenv("MONGO_URI")
+        if not uri:
+            raise RuntimeError("Set MEMTY_VAULT_MONGO_URI to use the MongoDB ledger backend")
+        return _mongo(uri, os.getenv("MEMORY_DATABASE", "Memory"),
+                      os.getenv("MEMTY_VAULT_MONGO_COLLECTION", os.getenv("NEXOR_VAULT_MONGO_COLLECTION", "memory_vault_ledger")), str(user_id))
+    if backend != "sqlite":
+        raise ValueError("MEMTY_VAULT_BACKEND must be sqlite or mongodb")
+    if path is None:
+        if os.getenv("MEMTY_VAULT_MULTIUSER", os.getenv("NEXOR_VAULT_MULTIUSER", "false")).casefold() == "true":
+            root = Path(os.getenv("MEMTY_VAULT_ROOT", Path.home() / ".memty" / "users"))
+            import hashlib
+            path = root / (hashlib.sha256(str(user_id).encode()).hexdigest() + ".sqlite3")
+        else:
+            path = default_vault_path()
+    return _sqlite(str(path), str(user_id))
+