docs: complete bilingual memory lifecycle RFC

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "powercontext",
       "source": "./integrations/claude-code/plugins/powercontext",
       "description": "Restore project memory and transfer current work from Claude Code",
-      "version": "0.1.0",
+      "version": "0.1.2",
       "category": "Productivity"
     }
   ]

.env.example

@@ -22,21 +22,30 @@ POWERCONTEXT_SERVER_HTTP_PORT=8000
 POWERCONTEXT_SERVER_MCP_ENABLED=true
 POWERCONTEXT_SERVER_MCP_PATH=/mcp
 
-# Authentication is optional on loopback. Load the real token from a secret manager.
-POWERCONTEXT_SERVER_AUTH_ENABLED=false
+# Access Control --------------------------------------------------------------
+# ACCESS_MODE is the only supported Access Control switch.
+POWERCONTEXT_SERVER_ACCESS_MODE=disabled
+# Legacy static Bearer compatibility. An injected Authentication Provider takes precedence.
+# POWERCONTEXT_SERVER_AUTH_ENABLED=true
 # POWERCONTEXT_SERVER_AUTH_TOKEN=replace-me
+POWERCONTEXT_SERVER_ACCESS_DEPLOYMENT_ID=powercontext
+# Multi-user deployments with background capabilities must bind an explicit service Principal.
+# POWERCONTEXT_SERVER_ACCESS_BACKGROUND_PRINCIPAL_ID=service:scheduled-processing
+# POWERCONTEXT_SERVER_ACCESS_BACKGROUND_PRINCIPAL_DESCRIPTION=Scheduled processing
 
 # Dashboard -------------------------------------------------------------------
-# The Dashboard discovers Scopes from the Server. The Server creates a default Scope on first startup.
-POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true
+# Personal/demo viewer. Enabling requires ACCESS_MODE=enforced and a static AUTH_TOKEN.
+# Injected authentication or authorization Providers are not supported by the Dashboard.
+POWERCONTEXT_SERVER_DASHBOARD_ENABLED=false
 
 # Logging, metrics, and tracing -----------------------------------------------
 POWERCONTEXT_SERVER_LOGGING_LEVEL=INFO
 POWERCONTEXT_SERVER_LOGGING_FORMAT=console
 POWERCONTEXT_SERVER_LOGGING_ACCESS=true
 POWERCONTEXT_SERVER_METRICS_ENABLED=true
 POWERCONTEXT_SERVER_TRACING_ENABLED=false
-# OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:6006/v1/traces
+# The OpenTelemetry SDK appends /v1/traces to this base URL.
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:6006
 # OTEL_SERVICE_NAME=powercontext
 
 # Database --------------------------------------------------------------------
@@ -53,15 +62,39 @@ POWERCONTEXT_SERVER_DATABASE_KIND=sqlite
 # POWERCONTEXT_SERVER_DATABASE_KIND=oceanbase
 # POWERCONTEXT_SERVER_DATABASE_URL=mysql+aoceanbase://user:password@host:2881/powercontext?charset=utf8mb4
 
-# Embedded seekDB alternative: install powercontext[cli,server,seekdb], then replace the SQLite kind.
+# Embedded seekdb alternative: install powercontext[cli,server,seekdb], then replace the SQLite kind.
 # Leave DATABASE_PATH unset to use the seekdb subdirectory below POWERCONTEXT_HOME.
 # POWERCONTEXT_SERVER_DATABASE_KIND=seekdb
 # POWERCONTEXT_SERVER_DATABASE_PATH=/absolute/path/to/seekdb
 
 # Runtime ---------------------------------------------------------------------
 POWERCONTEXT_SERVER_RUNTIME_SOURCE_WINDOW_LIMIT=100
+# Maximum sum of explicit assembly section limits; per-family limits still apply.
+POWERCONTEXT_SERVER_RUNTIME_CONTEXT_ASSEMBLY_MAX_ENTRIES=8
 POWERCONTEXT_SERVER_RUNTIME_MEMORY_EXTRACTION_PROFILE=coding
-POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS=60
+POWERCONTEXT_SERVER_RUNTIME_MEMORY_SCHEDULE_SECONDS=60
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_SCHEDULE_SECONDS=60
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_SOURCE_WINDOW_LIMIT=10
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_HISTORY_MAX_CANDIDATES=20
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_HISTORY_RRF_THRESHOLD=70
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_HISTORY_MIN_CANDIDATES=5
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_MAX_WORKERS=10
+POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_WORKER_TIMEOUT_SECONDS=600
+POWERCONTEXT_SERVER_RUNTIME_ARTIFACT_PROCESSING_ROLE=all
+POWERCONTEXT_SERVER_RUNTIME_ARTIFACT_PROCESSING_SUPERVISOR_MODE=global
+# Each Family owns its quota; dedicated creates one controller per Family.
+# POWERCONTEXT_SERVER_RUNTIME_MEMORY_MAX_WORKERS=1
+# POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_MAX_WORKERS=1
+POWERCONTEXT_SERVER_RUNTIME_SKILL_MAX_WORKERS=1
+POWERCONTEXT_SERVER_RUNTIME_SKILL_WORKER_TIMEOUT_SECONDS=600
+# Explicit Dream requests run through the Experience and Skill Supervisors.
+POWERCONTEXT_SERVER_RUNTIME_DREAM_ENABLED=true
+POWERCONTEXT_SERVER_RUNTIME_DREAM_MAX_PENDING_PER_SCOPE=32
+# POWERCONTEXT_SERVER_RUNTIME_DREAM_BUDGET='{"max_model_calls":2,"timeout_seconds":120}'
+# POWERCONTEXT_SERVER_RUNTIME_PROFILE_MAX_WORKERS=4
+# All migrated Families default to a 600-second total Scope invocation timeout.
+# Old SCHEDULE_SECONDS, PROFILE_MAX_CONCURRENCY, and ARTIFACT_PROCESSING_MAX_WORKERS/
+# WORKER_TIMEOUT_SECONDS remain aliases; conflicting old/new values fail startup.
 
 # Optional generation-backed jobs. Enable only when their extra model cost is intended.
 # POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_ENABLED=true
@@ -72,6 +105,7 @@ POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS=60
 # Generation and Embedding may use different providers; `powercontext config init` configures valid combinations.
 POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS=30
 POWERCONTEXT_SERVER_INFERENCE_GENERATION_MAX_REQUESTS=2
+POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL_CONTEXT_WINDOW_TOKENS=125000
 # Optional Pydantic AI model settings. Provider-specific request fields belong under `extra_body`.
 # POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL_SETTINGS='{"extra_body":{"chat_template_kwargs":{"enable_thinking":false}}}'
 POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION=unit

.github/actions/setup-python-env/action.yml

@@ -14,12 +14,12 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - uses: actions/setup-python@v7
+    - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
       with:
         python-version: ${{ inputs.python-version }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v10.0.0
+      uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
       with:
         version: ${{ inputs.uv-version }}
         enable-cache: 'true'

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/scripts/report_pytest_failures.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Expose pytest JUnit failures as public GitHub Actions annotations."""
+
+from __future__ import annotations
+
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+
+def _escape(value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def main() -> int:
+    report = Path(sys.argv[1])
+    if not report.is_file():
+        print(f"::error title=pytest report missing::{_escape(str(report))}")
+        return 0
+
+    root = ET.parse(report).getroot()  # noqa: S314 - parses a local pytest report
+    for case in root.iter("testcase"):
+        problem = next((case.find(kind) for kind in ("failure", "error") if case.find(kind) is not None), None)
+        if problem is None:
+            continue
+        identity = ".".join(filter(None, (case.get("classname"), case.get("name"))))
+        summary = (problem.get("message") or "pytest failed").strip()
+        traceback = (problem.text or "").strip()
+        detail = f"{summary}\n{traceback}" if traceback else summary
+        print(f"::error title={_escape(identity)}::{_escape(detail[:8000])}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/workflows/build-artifacts.yml

@@ -43,18 +43,19 @@ jobs:
 
     steps:
       - name: Check out requested source
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           ref: ${{ inputs.ref || github.sha }}
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@v7
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v10.0.0
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -261,6 +262,7 @@ jobs:
               "SessionStart": "session_binding.py",
               "PreToolUse": "bind_tools.py",
               "UserPromptSubmit": "recall.py",
+              "Stop": "token_savings.py",
           }
           for event, script in hook_scripts.items():
               hook = hooks["hooks"][event][0]["hooks"][0]
@@ -400,7 +402,7 @@ jobs:
             > "build/output/${ARTIFACT_NAME}.tar.gz.sha256"
 
       - name: Upload customer artifact
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: ${{ steps.metadata.outputs.artifact_name }}
           path: |

.github/workflows/build-docker.yml

@@ -21,21 +21,22 @@ jobs:
 
     steps:
       - name: Check out
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v10.0.0
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           version: "0.10.12"
           enable-cache: true
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@1f40c72289eff860ee54a304f1438e3cff362e0a # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
 
       - name: Resolve image metadata
         id: metadata
@@ -116,7 +117,7 @@ jobs:
           exit 1
 
       - name: Upload Docker image archives
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: ${{ steps.metadata.outputs.artifact_name }}
           path: docker-images/*.tar

.github/workflows/deploy-docs.yml

@@ -1,4 +1,4 @@
-name: Deploy documentation
+name: Deploy website
 
 on:
   workflow_dispatch:
@@ -13,27 +13,43 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  deploy-docs:
-    if: github.ref == 'refs/heads/master'
+  deploy-website:
+    if: >-
+      github.repository == 'oceanbase/powercontext' && github.ref == 'refs/heads/master'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      NEXT_PUBLIC_BASE_PATH: ''
+      NEXT_PUBLIC_SITE_URL: https://powercontext.oceanbase.io
+      NEXT_PUBLIC_REPOSITORY_URL: https://github.com/oceanbase/powercontext
     steps:
       - name: Check out
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
 
       - name: Set up the environment
         uses: ./.github/actions/setup-python-env
 
-      - name: Build documentation
+      - name: Set up website tools
+        uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2
+
+      - name: Build website
         run: make docs-build
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
+      - name: Upload website artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:
-          path: site
+          path: website/out
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5

.github/workflows/e2e-harness.yml

@@ -12,7 +12,7 @@ permissions:
   contents: read
 
 env:
-  TRUFFLEHOG_IMAGE: ghcr.io/trufflesecurity/trufflehog:3.96.0
+  TRUFFLEHOG_IMAGE: ghcr.io/trufflesecurity/trufflehog@sha256:562bc231afa9de3d04de44cfe624252b08207de1fc3cebc5e7ed92bed7f279e4 # v3.97.4
   UV_VERSION: "0.10.12"
 
 concurrency:
@@ -22,14 +22,16 @@ concurrency:
 jobs:
   validate:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Check out
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.0.0
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           version: ${{ env.UV_VERSION }}
 
@@ -50,16 +52,18 @@ jobs:
     name: Acceptance (${{ matrix.database }})
     steps:
       - name: Check out
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.0.0
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           version: ${{ env.UV_VERSION }}
 
       - name: Run deterministic scenarios
+        id: acceptance_scenarios
         env:
           POWERCONTEXT_E2E_DATABASE: ${{ matrix.database }}
           POWERCONTEXT_E2E_OUTPUT: ${{ github.workspace }}/.powercontext-e2e/${{ matrix.database }}/acceptance
@@ -68,33 +72,28 @@ jobs:
       - name: Scan replay evidence
         id: evidence_scan
         if: always()
-        continue-on-error: true
         env:
+          DATABASE: ${{ matrix.database }}
+          DIAGNOSTICS_PATH: ${{ runner.temp }}/powercontext-e2e-diagnostics-${{ matrix.database }}
           EVIDENCE_PATH: ${{ github.workspace }}/.powercontext-e2e/${{ matrix.database }}/acceptance
-        run: |
-          test -d "${EVIDENCE_PATH}"
-          if ! find "${EVIDENCE_PATH}" -type f -print -quit | grep -q .; then
-            echo "No replay evidence was produced." >&2
-            exit 1
-          fi
-          docker run --rm \
-            --volume "${EVIDENCE_PATH}:/evidence:ro" \
-            "${TRUFFLEHOG_IMAGE}" \
-            filesystem /evidence \
-            --no-verification \
-            --results=verified,unknown,unverified \
-            --fail \
-            --fail-on-scan-errors \
-            --no-update \
-            --json > "${RUNNER_TEMP}/trufflehog-acceptance-${{ matrix.database }}.jsonl"
+          SCENARIO_OUTCOME: ${{ steps.acceptance_scenarios.outcome }}
+        run: bash scripts/scan_e2e_evidence.sh
 
-      - name: Report suppressed replay evidence
-        if: always() && steps.evidence_scan.outcome != 'success'
-        run: echo "::warning::Replay evidence was missing or secret scanning did not complete cleanly."
+      - name: Upload sanitized replay diagnostics
+        if: >-
+          always() &&
+          (steps.evidence_scan.outcome != 'success' ||
+           steps.acceptance_scenarios.outcome != 'success')
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: e2e-acceptance-diagnostics-${{ matrix.database }}-${{ github.sha }}
+          path: ${{ runner.temp }}/powercontext-e2e-diagnostics-${{ matrix.database }}/summary.txt
+          if-no-files-found: error
+          retention-days: 14
 
       - name: Upload replay evidence
         if: always() && steps.evidence_scan.outcome == 'success'
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: e2e-acceptance-${{ matrix.database }}-${{ github.sha }}
           path: .powercontext-e2e/${{ matrix.database }}/acceptance