rememberstack 0.2.0__tar.gz → 0.4.0__tar.gz

rememberstack-0.4.0/.env.example

@@ -0,0 +1,76 @@
+# Local-only quickstart credentials. Replace every secret before exposing the stack.
+REMEMBERSTACK_POSTGRES_USER=rememberstack
+REMEMBERSTACK_POSTGRES_PASSWORD=rememberstack-local-only
+REMEMBERSTACK_POSTGRES_DB=rememberstack
+REMEMBERSTACK_MINIO_ACCESS_KEY=rememberstack-local
+REMEMBERSTACK_MINIO_SECRET_KEY=rememberstack-local-only
+
+# One stable deployment identity; changing it creates a different trust domain.
+REMEMBERSTACK_SELFHOST_DEPLOYMENT_ID=11111111-1111-4111-8111-111111111111
+REMEMBERSTACK_SELFHOST_DEPLOYMENT_SLUG=local
+REMEMBERSTACK_SELFHOST_DEPLOYMENT_NAME=Local memory
+REMEMBERSTACK_SELFHOST_API_PORT=8000
+# Where clients and the benchmark CLI look for that API. It defaults to
+# http://127.0.0.1:8000 independently of the port above, so if you change
+# REMEMBERSTACK_SELFHOST_API_PORT you must set this too or every client call
+# fails with "Connection refused" against the old port.
+# REMEMBERSTACK_API_URL=http://127.0.0.1:8000
+
+# Optional content-free cost export (D91). Unset bind means no HTTP export.
+# The listener is a second bind in the API process — not a route on the query API.
+# Token must be at least 32 bytes when the bind is set.
+# REMEMBERSTACK_COST_EXPORT_BIND=127.0.0.1:8001
+# REMEMBERSTACK_COST_EXPORT_TOKEN=
+
+# Optional CLI device-grant login (D92). Never derived from REMEMBERSTACK_API_URL.
+# REMEMBERSTACK_TOKEN_HOST=
+# REMEMBERSTACK_CONFIG_DIR=
+
+# Required to start the provider adapter. Replace this value before processing
+# a corpus; the complete Compose pipeline makes extraction and embedding calls.
+REMEMBERSTACK_OPENROUTER_API_KEY=replace-before-real-use
+# Optional exact OpenRouter embedding-provider slug (hard pin, no failover).
+# Prefer EMBEDDING_PROVIDER_ORDER for price-bounded multi-host routing.
+# REMEMBERSTACK_OPENROUTER_EMBEDDING_PROVIDER=nebius
+# Ordered shortlist for qwen/qwen3-embedding-8b hosts (order wins over hard pin).
+# Policy: design/operations/openrouter-embedding-routing.md
+# REMEMBERSTACK_OPENROUTER_EMBEDDING_PROVIDER_ORDER=nebius,deepinfra,siliconflow
+# 32k covers reasoning plus content; the provider account cap remains the monetary boundary.
+REMEMBERSTACK_OPENROUTER_MAX_COMPLETION_TOKENS=32000
+# Optional global reasoning effort for every chat-generation call. Allowed:
+# none, minimal, low, medium, high, xhigh, max. Unset uses the model default;
+# "none" reduces extraction latency but can reduce adjudication quality, and
+# models that require reasoning may reject it.
+# REMEMBERSTACK_OPENROUTER_REASONING_EFFORT=none
+# Optional per-model overrides as a JSON object of model-id → effort. A model's
+# entry wins over the global pin above; models absent from the map fall back to
+# the global pin (or the model default when that is also unset). Same allowed
+# effort literals. Example: pin flash models to none while keeping high for a
+# reasoning model.
+# REMEMBERSTACK_OPENROUTER_REASONING_EFFORT_MAP={"z-ai/glm-4.7-flash":"none","openai/gpt-5.6-luna":"high"}
+# Debug only: retain raw schema-invalid completions under the private app-state
+# volume. Disabled by default because captured output may repeat source text.
+# REMEMBERSTACK_OPENROUTER_INVALID_COMPLETION_CAPTURE_DIR=/var/lib/rememberstack/openrouter-invalid-completions
+
+# OBSERVABILITY (optional; empty or unset keeps all exporters disabled).
+# Sentry-protocol error tracking works with Sentry, GlitchTip, and Bugsink.
+# The environment defaults to REMEMBERSTACK_SELFHOST_DEPLOYMENT_SLUG and the
+# error-event sample rate defaults to 1.0.
+# REMEMBERSTACK_SENTRY_DSN=
+# REMEMBERSTACK_SENTRY_ENVIRONMENT=
+# REMEMBERSTACK_SENTRY_SAMPLE_RATE=1.0
+# LoCoMo answer/judge tracing activates only when all three values are non-empty.
+# LANGFUSE_PUBLIC_KEY=
+# LANGFUSE_SECRET_KEY=
+# LANGFUSE_HOST=https://cloud.langfuse.com
+
+# Optional benchmark/deployment model overrides. Keep explicit model IDs for a
+# reproducible run; do not use a rotating router such as openrouter/free.
+# REMEMBERSTACK_E2_EXTRACT_MODEL=nvidia/nemotron-3-super-120b-a12b:free
+# REMEMBERSTACK_E3_NORMALIZE_MODEL=nvidia/nemotron-3-super-120b-a12b:free
+# D79 structure seats: STRUCTURER names only the string-anchor fallback
+# proposer; the routine skeleton path is deterministic and calls no model.
+# REMEMBERSTACK_STRUCTURER_MODEL=openai/gpt-5.6-luna
+# REMEMBERSTACK_SKELETON_CHECK_MODEL=z-ai/glm-4.7-flash
+# REMEMBERSTACK_ROLE_MODEL=z-ai/glm-4.7-flash
+# REMEMBERSTACK_SUMMARY_MODEL=z-ai/glm-4.7-flash

rememberstack-0.4.0/.github/ci/check_test_inventory.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Fail if test inventory drifts: every test file in unit XOR integration, every path exists."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+TESTS = ROOT / "src" / "tests"
+UNIT = ROOT / ".github" / "ci" / "unit-paths.txt"
+INTEG = ROOT / ".github" / "ci" / "integration-paths.txt"
+
+# Soft PR lanes must be able to reach every integration file via these prefixes.
+SOFT_PREFIXES = (
+    "src/tests/workers/",
+    "src/tests/spine/",
+    "src/tests/surfaces/",
+    "src/tests/eval/",
+    "src/tests/adapters/",
+    "src/tests/profiles/",
+    "src/tests/spikes/",
+)
+
+
+def _load(path: Path) -> list[str]:
+    lines = [
+        line.strip()
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+    return lines
+
+
+def main() -> int:
+    unit = _load(UNIT)
+    integ = _load(INTEG)
+    errors: list[str] = []
+
+    unit_set = set(unit)
+    integ_set = set(integ)
+    overlap = sorted(unit_set & integ_set)
+    if overlap:
+        errors.append("paths in both unit and integration:\n  " + "\n  ".join(overlap))
+
+    for label, paths in (("unit", unit), ("integration", integ)):
+        missing = [p for p in paths if not (ROOT / p).is_file()]
+        if missing:
+            errors.append(f"{label} lists missing files:\n  " + "\n  ".join(missing))
+
+    discovered = sorted(
+        str(path.relative_to(ROOT)) for path in TESTS.rglob("test_*.py")
+    )
+    covered = unit_set | integ_set
+    orphans = [p for p in discovered if p not in covered]
+    if orphans:
+        errors.append("test files not in any inventory:\n  " + "\n  ".join(orphans))
+
+    unreachable = [
+        p
+        for p in integ
+        if not any(p.startswith(prefix) for prefix in SOFT_PREFIXES)
+    ]
+    if unreachable:
+        errors.append(
+            "integration files unreachable by soft PR lanes:\n  "
+            + "\n  ".join(unreachable)
+        )
+
+    if errors:
+        print("test inventory check FAILED:\n")
+        print("\n\n".join(errors))
+        return 1
+    print(
+        f"test inventory OK: unit={len(unit)} integration={len(integ)} "
+        f"discovered={len(discovered)}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rememberstack-0.4.0/.github/ci/contract-smoke-paths.txt

@@ -0,0 +1,8 @@
+src/tests/spine/test_migrations.py
+src/tests/spine/test_rank_embed_cache.py
+src/tests/eval/test_harness_skeleton.py
+src/tests/test_smoke.py
+src/tests/model/test_component_version.py
+src/tests/model/test_deployment.py
+src/tests/core/test_embedding_input_policy.py
+src/tests/adapters/test_openrouter.py

rememberstack-0.4.0/.github/ci/integration-paths.txt

@@ -0,0 +1,55 @@
+src/tests/adapters/test_mount_provisioning.py
+src/tests/adapters/test_selfhost_queue.py
+src/tests/eval/test_harness_skeleton.py
+src/tests/eval/test_s58_consumption.py
+src/tests/profiles/test_selfhost_profile.py
+src/tests/spikes/test_operational_scale.py
+src/tests/spikes/test_p2_engine_spikes.py
+src/tests/spikes/test_retrieval_spikes.py
+src/tests/spine/test_backfill.py
+src/tests/spine/test_clustering.py
+src/tests/spine/test_component_versions.py
+src/tests/spine/test_deployment_bootstrap.py
+src/tests/spine/test_forget_catalog.py
+src/tests/spine/test_governance.py
+src/tests/spine/test_knowledge_commit_driver.py
+src/tests/spine/test_knowledge_control_plane.py
+src/tests/spine/test_migrations.py
+src/tests/spine/test_observation_adjudication.py
+src/tests/spine/test_operations.py
+src/tests/spine/test_pipeline_readiness.py
+src/tests/spine/test_query_space_batch_a.py
+src/tests/spine/test_resolver.py
+src/tests/spine/test_review_queue.py
+src/tests/spine/test_supersession.py
+src/tests/spine/test_unmerge_ripple.py
+src/tests/spine/test_work_ledger.py
+src/tests/surfaces/test_cost_export.py
+src/tests/surfaces/test_envelope_contract.py
+src/tests/surfaces/test_graph_queries.py
+src/tests/surfaces/test_open_query_batch_f.py
+src/tests/surfaces/test_ops_cli.py
+src/tests/surfaces/test_query_sandbox_batch_b.py
+src/tests/surfaces/test_query_sandbox_batch_c.py
+src/tests/surfaces/test_query_sandbox_batch_d.py
+src/tests/surfaces/test_operation_registry.py
+src/tests/surfaces/test_retrieval_api.py
+src/tests/surfaces/test_retrieval_batch_b.py
+src/tests/surfaces/test_retrieval_batch_c.py
+src/tests/surfaces/test_retrieval_batch_d.py
+src/tests/surfaces/test_retrieval_batch_e.py
+src/tests/surfaces/test_retrieval_primitives.py
+src/tests/surfaces/test_saved_queries_batch_e.py
+src/tests/surfaces/test_surface_cost.py
+src/tests/surfaces/test_surfaces_parity.py
+src/tests/workers/test_claimify_loss_ledger_pg.py
+src/tests/workers/test_e0_chain.py
+src/tests/workers/test_e1_chain.py
+src/tests/workers/test_e2_chain.py
+src/tests/workers/test_e3_chain.py
+src/tests/workers/test_lifecycle_reconciliation.py
+src/tests/workers/test_p2_analytics.py
+src/tests/workers/test_p2_rebuild.py
+src/tests/workers/test_p3_corpusfs.py
+src/tests/workers/test_reuse_lifecycle.py
+src/tests/workers/test_watch_loop.py

rememberstack-0.4.0/.github/ci/path-filters.yml

@@ -0,0 +1,74 @@
+# Maps source areas to integration test directories / compose.
+# Shared-core paths expand to a broader pack (see ci.yml).
+quality:
+  - 'src/**'
+  - 'benchmarks/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+  - '.github/workflows/**'
+  - '.github/ci/**'
+  - 'ruff.toml'
+  - 'alembic.ini'
+
+unit:
+  - 'src/**'
+  - 'benchmarks/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+  - '.github/ci/unit-paths.txt'
+
+contract:
+  - 'src/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+  - 'alembic.ini'
+  - 'src/rememberstack/spine/migrations/**'
+  - '.github/ci/contract-smoke-paths.txt'
+
+workers:
+  - 'src/rememberstack/workers/**'
+  - 'src/rememberstack/spine/**'
+  - 'src/rememberstack/model/**'
+  - 'src/tests/workers/**'
+  - 'src/tests/spine/**'
+
+surfaces:
+  - 'src/rememberstack/surfaces/**'
+  - 'src/rememberstack/spine/query_space/**'
+  - 'src/rememberstack/spine/projection.py'
+  - 'src/rememberstack/spine/resolver.py'
+  - 'src/rememberstack/core/**'
+  - 'src/tests/surfaces/**'
+  - 'src/tests/eval/**'
+
+adapters:
+  - 'src/rememberstack/adapters/**'
+  - 'src/rememberstack/profiles/**'
+  - 'src/tests/adapters/**'
+  - 'src/tests/profiles/**'
+  - 'src/tests/spikes/**'
+  - 'src/tests/test_*.py'
+
+compose:
+  - 'compose.yaml'
+  - 'Dockerfile'
+  - '.github/compose/**'
+  - '.env.example'
+  - 'src/rememberstack/profiles/**'
+  - 'src/rememberstack/adapters/selfhost/**'
+  - 'pyproject.toml'
+  - 'uv.lock'
+
+# Touching these forces the broad integration pack on PRs.
+shared_core:
+  - 'src/rememberstack/model/**'
+  - 'src/rememberstack/ports/**'
+  - 'src/rememberstack/spine/**'
+  - 'src/rememberstack/workers/base.py'
+  - 'src/rememberstack/profiles/**'
+
+# CI control plane changes must exercise soft lanes on their own PR.
+ci_control:
+  - '.github/workflows/ci.yml'
+  - '.github/workflows/ci-nightly.yml'
+  - '.github/ci/**'

rememberstack-0.4.0/.github/ci/unit-paths.txt

@@ -0,0 +1,68 @@
+src/tests/adapters/test_codex_writer.py
+src/tests/adapters/test_lance_retrieval.py
+src/tests/adapters/test_minio_store.py
+src/tests/adapters/test_openrouter.py
+src/tests/adapters/test_selfhost_forget.py
+src/tests/adapters/test_selfhost_git.py
+src/tests/adapters/test_selfhost_purge.py
+src/tests/adapters/test_selfhost_stores.py
+src/tests/adapters/test_sentry.py
+src/tests/adapters/test_telemetry.py
+src/tests/benchmarks/test_beam_answer_agent.py
+src/tests/benchmarks/test_beam_official_score.py
+src/tests/benchmarks/test_locomo_dataset.py
+src/tests/benchmarks/test_locomo_protocol.py
+src/tests/benchmarks/test_locomo_retrieval.py
+src/tests/benchmarks/test_locomo_runner.py
+src/tests/benchmarks/test_locomo_sharding.py
+src/tests/benchmarks/test_locomo_store_backup.py
+src/tests/core/test_blockizer_corpus.py
+src/tests/core/test_chunker.py
+src/tests/core/test_consumption_skill.py
+src/tests/core/test_conversion.py
+src/tests/core/test_core_manifest.py
+src/tests/core/test_d80_recovery_and_hydration.py
+src/tests/core/test_embedding_input_policy.py
+src/tests/core/test_forget_identity.py
+src/tests/core/test_knowledge_authored.py
+src/tests/core/test_knowledge_compile.py
+src/tests/core/test_knowledge_fact_sheet.py
+src/tests/core/test_knowledge_hashing.py
+src/tests/core/test_knowledge_planner.py
+src/tests/core/test_knowledge_writer.py
+src/tests/core/test_section_snap.py
+src/tests/core/test_structure_skeleton.py
+src/tests/eval/test_s55_hard_forget.py
+src/tests/eval/test_s55_selfhost_restore.py
+src/tests/model/test_component_version.py
+src/tests/model/test_deployment.py
+src/tests/model/test_forget.py
+src/tests/packaging/test_client_wheel.py
+src/tests/packaging/test_release_contract.py
+src/tests/spine/test_catalog_lanes.py
+src/tests/spine/test_query_space_manifest.py
+src/tests/spine/test_rank_embed_cache.py
+src/tests/surfaces/test_assured_operation_authorities.py
+src/tests/surfaces/test_client_sdk.py
+src/tests/surfaces/test_cost_export_contract.py
+src/tests/surfaces/test_forget_admission.py
+src/tests/surfaces/test_login.py
+src/tests/surfaces/test_mcp_memory_tools.py
+src/tests/test_forget_port_contract.py
+src/tests/test_port_inventory_and_conformance.py
+src/tests/test_port_model_values.py
+src/tests/test_queue_port_contract.py
+src/tests/test_smoke.py
+src/tests/workers/test_chunk_level_extract.py
+src/tests/workers/test_claim_valid_time.py
+src/tests/workers/test_claimify_loss_ledger.py
+src/tests/workers/test_d79_structure_route.py
+src/tests/workers/test_d79_summaries.py
+src/tests/workers/test_d79_summary_consumption.py
+src/tests/workers/test_e3_claim_normalize_fanout.py
+src/tests/workers/test_e3_entity_obs_flush_fanout.py
+src/tests/workers/test_e3_unknown_entity_type_gate.py
+src/tests/workers/test_extraction_temperature.py
+src/tests/workers/test_hard_forget_handler.py
+src/tests/workers/test_hard_forget_service.py
+src/tests/workers/test_ingest_admission.py

rememberstack-0.4.0/.github/workflows/ci-nightly.yml

@@ -0,0 +1,119 @@
+name: Nightly CI
+
+# Full multi-Python suite + coverage. Not required for PR merge.
+# See design/operations/pr-ci-fast-gate.md
+
+on:
+  schedule:
+    # 05:17 UTC daily — offset from hour to avoid schedule storms
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: nightly-ci
+  cancel-in-progress: false
+
+jobs:
+  compose-quickstart:
+    name: Compose quickstart
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    env:
+      QUICKSTART_TARGET_SECONDS: "600"
+      REMEMBERSTACK_BUILD_REVISION: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate Compose model
+        run: docker compose --env-file .env.example config --quiet
+      - name: Start fresh self-host deployment
+        run: |
+          started_at="$(date +%s)"
+          docker compose --env-file .env.example up --build --detach --wait
+          curl --fail http://localhost:8000/operations
+          served_revision="$(curl --fail --silent http://localhost:8000/deployment \
+            | python3 -c 'import json,sys; print(json.load(sys.stdin)["build_revision"])')"
+          test "$served_revision" = "${REMEMBERSTACK_BUILD_REVISION}"
+          elapsed_seconds="$(($(date +%s) - started_at))"
+          echo "Quickstart cold start to first query: ${elapsed_seconds}s / ${QUICKSTART_TARGET_SECONDS}s target" \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+          test "$elapsed_seconds" -le "$QUICKSTART_TARGET_SECONDS"
+      - name: Remove quickstart deployment
+        if: always()
+        run: docker compose --env-file .env.example down --volumes
+
+  checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    permissions:
+      contents: read
+    env:
+      REMEMBERSTACK_DATABASE_URL: postgresql+psycopg://rememberstack:rememberstack_test@localhost:5432/rememberstack_test
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    services:
+      postgres:
+        image: ghcr.io/dbsystel/postgresql-partman@sha256:bf9d2331aaeb3e33a4e6e73b4c024ca618d4d1ea050bbab978125ff63b83385a
+        env:
+          POSTGRES_USER: rememberstack
+          POSTGRES_PASSWORD: rememberstack_test
+          POSTGRES_DB: rememberstack_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U rememberstack -d rememberstack_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python ${{ matrix.python-version }}
+      - name: Architecture dependency check
+        run: uv run lint-imports
+      - name: Ruff lint
+        run: uv run ruff check src/ benchmarks/
+      - name: Ruff format check
+        run: uv run ruff format --check src/ benchmarks/
+      - name: Pyright type check
+        run: uv run pyright src/ benchmarks/ --pythonversion ${{ matrix.python-version }}
+      - name: Real PostgreSQL Alembic lifecycle
+        run: uv run pytest src/tests/spine/test_migrations.py -v --tb=short
+      - name: Full tests (with coverage)
+        run: uv run pytest src/tests -v --tb=short --cov --cov-report=term
+        env:
+          COVERAGE_FILE: .coverage.${{ matrix.python-version }}
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-nightly-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+
+  coverage:
+    name: Coverage report
+    runs-on: ubuntu-latest
+    needs: checks
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download coverage data
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-nightly-*
+          merge-multiple: true
+      - name: Coverage comment + badge
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          MERGE_COVERAGE_FILES: true