feat(mcp): add explicit local agent memory and learning tools

.github/workflows/ci.yml

@@ -107,12 +107,12 @@ jobs:
       - run: cargo build --workspace
       - run: cargo test --workspace --lib --no-fail-fast
       - name: Persist and recover authored memory through the CLI
-        run: cargo test --locked -p terraphim_agent --test memory_capture_cli_tests --test memory_apply_cli_tests --test memory_rubric_cli_tests
+        run: cargo test --locked -p terraphim_agent --test memory_capture_cli_tests --test memory_apply_cli_tests --test memory_rubric_cli_tests --test agent_store_contract --test agent_learning_store_contract
       # Exercise the released grep command against real files and exported
       # synonym graphs, including Linux-only hostile filesystem names.
       - run: cargo test --locked -p terraphim_grep --test synonym_retrieval --test answer_request --test path_guard_hostile_tree --test single_file_search
       - name: Verify authored synonyms and role boundaries over real MCP stdio
-        run: cargo test --locked -p terraphim_mcp_server --test test_mcp_role_contract
+        run: cargo test --locked -p terraphim_mcp_server --test test_mcp_role_contract --test test_mcp_agent_contract
       # GitHub-side home for the updater integration contracts (managed-mode
       # receipt/refusal, strict v2 manifest readers, R2 checksum fail-closed).
       # On Gitea these lanes live in .gitea/workflows/native-ci.yml, which is

.github/workflows/pkgbuild-contract.yml

@@ -11,11 +11,15 @@ on:
       - "pkgbuilds/terraphim-clients-bin/**"
       - "tests/test_pkgbuild_release_contract.py"
       - ".github/workflows/pkgbuild-contract.yml"
+      - "scripts/prepare-pkgbuild-stage.py"
+      - "tests/test_pkgbuild_stage.py"
   pull_request:
     paths:
       - "pkgbuilds/terraphim-clients-bin/**"
       - "tests/test_pkgbuild_release_contract.py"
       - ".github/workflows/pkgbuild-contract.yml"
+      - "scripts/prepare-pkgbuild-stage.py"
+      - "tests/test_pkgbuild_stage.py"
 
 permissions:
   contents: read
@@ -32,12 +36,90 @@ jobs:
   arch-package:
     name: arch build + install
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
     container:
       image: archlinux:base-devel
       options: --privileged
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Install namcap
         run: pacman -Sy --noconfirm --needed namcap
+      # Before public promotion the exact signed archives exist only in the
+      # sealed stage. Once all public archives exist, use makepkg's normal URL
+      # download path; do not depend on retained Actions artefacts indefinitely.
+      - name: Resolve reviewed stage identity
+        id: stage
+        run: python3 scripts/prepare-pkgbuild-stage.py pkgbuilds/terraphim-clients-bin/release-stage.json identity >> "$GITHUB_OUTPUT"
+      - name: Check whether the exact public release is complete
+        id: source
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.stage.outputs.version }}
+        run: |
+          set -euo pipefail
+          status="$(curl --silent --show-error -H "Authorization: Bearer $GH_TOKEN" \
+            -o "$RUNNER_TEMP/release.json" -w '%{http_code}' \
+            "https://api.github.com/repos/terraphim/terraphim-clients/releases/tags/v$VERSION")"
+          python3 scripts/prepare-pkgbuild-stage.py pkgbuilds/terraphim-clients-bin/release-stage.json \
+            mode "$status" "$RUNNER_TEMP/release.json" >> "$GITHUB_OUTPUT"
+      - name: Read exact producer and artefact metadata
+        if: steps.source.outputs.mode == 'stage'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_ID: ${{ steps.stage.outputs.run_id }}
+          ARTIFACT_ID: ${{ steps.stage.outputs.artifact_id }}
+        run: |
+          set -euo pipefail
+          curl --fail --silent --show-error -H "Authorization: Bearer $GH_TOKEN" \
+            "https://api.github.com/repos/terraphim/terraphim-clients/actions/runs/$RUN_ID" > "$RUNNER_TEMP/stage-run.json"
+          curl --fail --silent --show-error -H "Authorization: Bearer $GH_TOKEN" \
+            "https://api.github.com/repos/terraphim/terraphim-clients/actions/artifacts/$ARTIFACT_ID" > "$RUNNER_TEMP/stage-artifact.json"
+          python3 scripts/prepare-pkgbuild-stage.py pkgbuilds/terraphim-clients-bin/release-stage.json \
+            metadata "$RUNNER_TEMP/stage-run.json" "$RUNNER_TEMP/stage-artifact.json"
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        if: steps.source.outputs.mode == 'stage'
+        with:
+          artifact-ids: ${{ steps.stage.outputs.artifact_id }}
+          merge-multiple: true
+          path: ${{ runner.temp }}/${{ steps.stage.outputs.artifact_name }}
+          repository: terraphim/terraphim-clients
+          run-id: ${{ steps.stage.outputs.run_id }}
+          github-token: ${{ github.token }}
+      - name: Verify sealed provenance and cache exact native archives
+        if: steps.source.outputs.mode == 'stage'
+        env:
+          STAGE_NAME: ${{ steps.stage.outputs.artifact_name }}
+        run: |
+          set -euo pipefail
+          python3 scripts/prepare-pkgbuild-stage.py pkgbuilds/terraphim-clients-bin/release-stage.json \
+            prepare "$RUNNER_TEMP/$STAGE_NAME" "$RUNNER_TEMP/stage-run.json" \
+            "$RUNNER_TEMP/stage-artifact.json" pkgbuilds/terraphim-clients-bin "$(uname -m)" \
+            > "$RUNNER_TEMP/pkgbuild-stage-readback.json"
+          PKGBUILD_STAGE_TEST_DIR="$RUNNER_TEMP/$STAGE_NAME" \
+            PKGBUILD_STAGE_RUN_JSON="$RUNNER_TEMP/stage-run.json" \
+            PKGBUILD_STAGE_ARTIFACT_JSON="$RUNNER_TEMP/stage-artifact.json" \
+            python3 -W error::ResourceWarning -m unittest tests.test_pkgbuild_stage -v
       - name: Build, lint, install, smoke and remove
         run: ./pkgbuilds/terraphim-clients-bin/verify.sh
+      - name: Collect source-selection and cache readback
+        if: always()
+        run: |
+          set -euo pipefail
+          receipt_dir="$RUNNER_TEMP/pkgbuild-source-readback"
+          mkdir -p "$receipt_dir"
+          for name in release.json stage-run.json stage-artifact.json pkgbuild-stage-readback.json; do
+            if [ -f "$RUNNER_TEMP/$name" ]; then
+              cp "$RUNNER_TEMP/$name" "$receipt_dir/$name"
+            fi
+          done
+      - name: Retain source-selection and cache readback
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: pkgbuild-source-readback-${{ github.run_id }}-${{ github.run_attempt }}
+          # One path lets Actions translate the host mount into the job container.
+          path: ${{ runner.temp }}/pkgbuild-source-readback/
+          if-no-files-found: error
+          overwrite: false

Cargo.toml

@@ -15,7 +15,7 @@ members = [
 ]
 
 [workspace.package]
-version = "1.21.20"
+version = "1.21.22"
 edition = "2024"
 authors = ["Terraphim Team <team@terraphim.ai>"]
 documentation = "https://terraphim.ai"

README.md

@@ -3,7 +3,7 @@
 Client + integration crates extracted from terraphim-ai (#1910):
 
 - `terraphim-cli` / `terraphim_agent` -- CLI + agent REPL
-- `terraphim_mcp_server` -- MCP server
+- `terraphim_mcp_server` -- MCP server (graph tools and optional [local agent memory/learning tools](docs/mcp/agent-tools.md))
 - `terraphim_sessions` -- session import/search
 - `terraphim_lsp` -- LSP server (EDM diagnostics)
 - `terraphim_grep`, `terraphim_hooks`, `terraphim_update`, `terraphim_command_runtime`, `terraphim_negative_contribution`

crates/terraphim_agent/Cargo.toml

@@ -68,6 +68,7 @@ jiff = { version = "0.2", features = ["serde"] }
 strsim = "0.11"  # For edit distance / fuzzy matching in forgiving CLI
 uuid = { workspace = true }
 dialoguer = "0.12"  # Interactive CLI prompts for onboarding wizard
+tempfile = { workspace = true }
 sha2 = "0.10"  # Corpus and thesaurus hashes for the judge-free memory benchmark (#260)
 
 # REPL dependencies - only compiled with features