rememberstack 0.4.3__tar.gz → 0.5.0__tar.gz

rememberstack-0.5.0/.env.example

@@ -0,0 +1,91 @@
+# 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
+# Optional API perimeter. Unset = open quickstart. Managed hosts set
+# REQUIRE_API_AUTH=true and BIND={issued_deployment_uuid}:{sha256hex}.
+# REMEMBERSTACK_SELFHOST_API_BEARER_BIND=
+# REMEMBERSTACK_SELFHOST_API_BEARER_TOKEN=
+# REMEMBERSTACK_SELFHOST_REQUIRE_API_AUTH=false
+# Managed hosts also set the control-plane metadata spend lease (D46).
+# REMEMBERSTACK_SELFHOST_SPEND_LEASE_URL=
+# 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 dedicated live-graph resource bounds. These defaults match Compose;
+# managed hosts must size them together with the PostgreSQL memory admission
+# contract rather than increasing one value in isolation.
+# REMEMBERSTACK_SELFHOST_GRAPH_POOL_SIZE=4
+# REMEMBERSTACK_SELFHOST_GRAPH_POOL_TIMEOUT_S=1
+# REMEMBERSTACK_SELFHOST_GRAPH_MAX_CONCURRENCY=2
+# REMEMBERSTACK_SELFHOST_GRAPH_WORK_MEM_KIB=16384
+
+# 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.5.0/.github/ci/integration-paths.txt

@@ -0,0 +1,50 @@
+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/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_profile_refresher.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_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_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_p3_corpusfs.py
+src/tests/workers/test_reuse_lifecycle.py
+src/tests/workers/test_watch_loop.py

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

@@ -0,0 +1,73 @@
+# 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/**'
+compose:
+  - 'compose.yaml'
+  - 'Dockerfile'
+  - 'Dockerfile.postgres'
+  - '.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.5.0/.github/ci/unit-paths.txt

@@ -0,0 +1,75 @@
+src/tests/adapters/test_codex_writer.py
+src/tests/adapters/test_control_plane_spend_lease.py
+src/tests/adapters/test_hashed_bearer_auth.py
+src/tests/adapters/test_postgres_p1.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_entity_eligibility.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_graph_http_api.py
+src/tests/surfaces/test_login.py
+src/tests/surfaces/test_mcp_memory_tools.py
+src/tests/surfaces/test_postgres_graph_sql.py
+src/tests/surfaces/test_query_sandbox_graph_d98.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_d98_removal_audit.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_bare_head_noun.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.5.0/.github/workflows/ci-nightly.yml

@@ -0,0 +1,108 @@
+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"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start PostgreSQL 19 with required extensions
+        run: .github/ci/start-postgres.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.12.6"
+          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