Prepare BrainCore v1.2.0

.agents/TOOL_INDEX.yaml

@@ -47,6 +47,9 @@ tools:
   - name: memory-working-cleanup-expired
     description: mark expired unpromoted working-memory items as expired
     source: examples/mcp_server/server.py
+  - name: braincore-snapshot
+    description: build an audited BrainCore memory snapshot through the CLI-backed reference server
+    source: examples/mcp_server/server.py
   - name: memory-search-visual
     description: search OCR, caption, and layout metadata without exposing raw artifacts
     source: examples/mcp_server/server.py

.github/workflows/codeql.yml

@@ -31,12 +31,12 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@9e0d7b8d25671d64c341c19c0152d693099fb5ba
+        uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
 
       - name: Perform CodeQL analysis
-        uses: github/codeql-action/analyze@9e0d7b8d25671d64c341c19c0152d693099fb5ba
+        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa
         with:
           category: "/language:${{ matrix.language }}"

AGENTS.md

@@ -53,6 +53,29 @@ customers may inspect:
 8. Never commit generated image prompts or draft visual instructions into the
    public repo.
 
+## Dependabot Hard Rule
+
+Never merge a Dependabot-authored PR in this repository.
+
+This is a standing hard stop. It applies even if the user says "merge all PRs",
+"approved", "proceed", "finish the PRs", or similar broad approval language.
+Dependabot PRs are read-only dependency proposals only.
+
+Required handling:
+
+1. Inspect Dependabot PRs only as evidence of requested dependency changes.
+2. If a dependency update is accepted, create an organization-owned curated
+   branch from current `main` and apply the dependency change there.
+3. Run the full Gitea-first public release gate, security review, tests, and CI
+   on the curated branch/PR.
+4. Merge only the curated non-Dependabot PR after the gate passes.
+5. Close the Dependabot PR as superseded, deferred, or rejected with the reason
+   documented in the incident/release notes.
+
+If any open PR list includes `app/dependabot`, do not treat "all PRs" as a
+merge instruction for those PRs. Stop that part of the workflow and report that
+Dependabot PRs must be superseded by a curated branch instead.
+
 ## Human-readable boundaries
 
 - The example MCP server is a reference implementation only.

CHANGELOG.md

@@ -4,10 +4,21 @@ All notable changes to BrainCore are documented in this file.
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-05-23
+
 ### Added
 - Added additive memory governance migration `022_memory_governance.sql` with prompt recall, feedback, quality audit, context audit, lifecycle outbox, cue, compaction, and source attribution support.
+- Added additive assistant memory source migration `023_assistant_memory_sources.sql`
+  with `vestige_memory` and `pai_auto_memory` source types for deterministic
+  assistant-memory migration sources.
 - Added governed memory CLI commands for event ingestion, recall/read auditing, status updates, feedback, compaction, conflict detection, and source attribution.
 - Added memory governance policy checks to CI and local sanitization coverage.
+- Added assistant memory import review commands so imported assistant memories
+  stay non-prompt-eligible until operator review and memory governance approve
+  promotion.
+- Added audited BrainCore snapshot builds with compact, risk, and deep preload
+  profiles.
+- Added BrainCore shadow-eval support for snapshot behavior checks.
 
 ### Fixed
 - Governed prompt search now excludes archived, quarantined, suppressed, retired, and retired-superseded memories by default while preserving an explicit operator inspection override.
@@ -24,7 +35,7 @@ All notable changes to BrainCore are documented in this file.
 - Added CLI and MCP-first lifecycle administration surfaces. The browser/admin
   web app remains a future upgrade path.
 - The open-source preserve schema is now documented as 50 tables after
-  migrations `001` through `022` plus the runtime migration ledger bootstrap.
+  migrations `001` through `023` plus the runtime migration ledger bootstrap.
 - Lifecycle `suppressed` and `retired` overlays are enforced in retrieval and
   procedure search paths without mutating BrainCore native truth rows.
 - Memory governance metadata, lifecycle sensitivity/redaction values, and cue

CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 title: "BrainCore"
 message: "If you use BrainCore, please cite it using the metadata below."
-version: "1.1.6"
-date-released: "2026-04-30"
+version: "1.2.0"
+date-released: "2026-05-23"
 authors:
   - family-names: Doney
     given-names: Trent
@@ -29,7 +29,7 @@ preferred-citation:
     - family-names: Doney
       given-names: Trent
       name: "Trent Doney"
-  version: "1.1.6"
-  date-released: "2026-04-30"
+  version: "1.2.0"
+  date-released: "2026-05-23"
   repository-code: "https://github.com/SynapseGrid-Labs/BrainCore"
   url: "https://github.com/SynapseGrid-Labs/BrainCore"

CONTRIBUTING.md

@@ -20,7 +20,7 @@ what the repo actually ships:
 4. Do not turn the example MCP server into a claim that the repo ships a
    larger tool surface than it does.
 5. Keep the launch truth surface aligned: `001` through `021`,
-   `45-table preserve schema`, `v1.1.6`, and the committed benchmark
+   `50-table preserve schema`, `v1.2.0`, and the committed benchmark
    artifacts.
 6. Do not add, replace, regenerate, compress, optimize, or overwrite image
    assets unless the human owner supplied the final approved asset for this PR.

README.md

@@ -41,7 +41,7 @@ BrainCore processes operational artifacts and automatically:
 All knowledge is stored in PostgreSQL with pgvector, enabling four core retrieval streams (SQL + full-text + vector + temporal) plus optional graph-path retrieval with Reciprocal Rank Fusion.
 
 <p align="center">
-  <img src="assets/lifecycle-control-flow.jpg" alt="BrainCore memory lifecycle control flow showing retrieve, inject, omit, feedback, and control outcomes while native evidence remains unchanged." width="100%" />
+  <img src="assets/lifecycle-control-flow.jpg" alt="BrainCore v1.2 memory lifecycle control flow from sources through extraction, review, approved memory, snapshot retrieval, prompt packaging, feedback, suppression, retirement, and append-only audit logs." width="100%" />
 </p>
 
 ## Quality Standard
@@ -66,7 +66,7 @@ software:
 
 ## Features
 
-- **Source ingestion**: incident notes plus deterministic parsers for Claude Code, Codex, Codex shared memory, Discord, Telegram, Grafana, personal memory, Asana task exports, and Git commits
+- **Source ingestion**: incident notes plus deterministic parsers for Claude Code, Codex, Codex shared memory, Discord, Telegram, Grafana, personal memory, assistant memory exports, Asana task exports, Git commits, and curated project documentation
 - **Hybrid retrieval**: Structured SQL + FTS + vector similarity + temporal expansion, with optional graph path search, fused with RRF (`k=60`)
 - **Trust classes**: `deterministic`, `corroborated_llm`, `single_source_llm`, `human_curated`
 - **Enterprise memory lifecycle overlay**: Suppress or retire recall targets without destroying native evidence, with append-only feedback, score, and audit trails
@@ -313,7 +313,7 @@ data sources
 ```
 
 <p align="center">
-  <img src="assets/architecture.jpg" alt="BrainCore architecture diagram showing sources, archive, extract, consolidate, retrieve, publish, hybrid retrieval, and evidence audit guarantees." width="100%" />
+  <img src="assets/architecture.jpg" alt="BrainCore v1.2 architecture diagram showing source ingestion, archive, extract, load, review, governed memories, snapshot builder, MCP and CLI retrieval, storage indexes, audit lineage, and schema management." width="100%" />
 </p>
 
 ### Trust classes
@@ -457,9 +457,9 @@ The response includes:
 That makes it possible to debug retrieval behavior without guessing
 which stream contributed the hit.
 
-## The 9 Data Sources
+## The 12 Data Sources
 
-BrainCore currently ships `9 deterministic parsers`.
+BrainCore currently ships `12 deterministic source parsers`.
 
 | Parser | Input | Typical output |
 |---|---|---|
@@ -472,6 +472,9 @@ BrainCore currently ships `9 deterministic parsers`.
 | `personal-memory-parser.ts` | personal memory markdown | curated memory and reference facts |
 | `asana-parser.ts` | Asana task export JSON/JSONL | task state, routing, project, and custom-field facts |
 | `git-parser.ts` | git commit JSON/JSONL or local repository | commit timeline, author, and touched-file facts |
+| `pai-auto-memory-parser.ts` | PAI auto-memory markdown | imported assistant-memory facts for review-gated promotion |
+| `vestige-parser.ts` | Vestige JSON/JSONL export | imported assistant-memory facts for review-gated promotion |
+| `project-doc-parser.ts` | curated project documentation manifest | explicit project facts gated by value review |
 
 The repo also contains extractor infrastructure files such as
 `deterministic.ts`, `semantic.ts`, `quality-gate.ts`,

assets/README.md

@@ -8,8 +8,8 @@ active assets should be referenced by public docs.
 | File | Status | Dimensions | Format | Usage |
 |---|---|---|---|---|
 | `og.jpg` | Active | 1672 by 941 | JPEG | README hero block and social preview source |
-| `lifecycle-control-flow.jpg` | Active | 1672 by 941 | JPEG | README lifecycle control flow overview |
-| `architecture.jpg` | Active | 1672 by 941 | JPEG | README architecture section |
+| `lifecycle-control-flow.jpg` | Active | 1671 by 941 | JPEG | README lifecycle control flow overview |
+| `architecture.jpg` | Active | 1671 by 941 | JPEG | README architecture section |
 | `maintained-by-trent.jpg` | Active | 1200 by 397 | JPEG | README author note banner |
 | `manifest.json` | Reference | n/a | JSON | Hash and dimension manifest |
 | `README.md` | Reference | n/a | Markdown | Asset notes |

assets/manifest.json

@@ -9,66 +9,65 @@
       "format": "JPEG",
       "width": 1672,
       "height": 941,
-      "sha256": "3b88eef1b8df5994e58c7f2e208bcd9d976eeefbb1a31fcf0077e34043c7da3d",
+      "sha256": "4c579e101e0946225bc5f430babcff5cf0ccdeb476020dbe06fb605b7c3b5ca9",
       "visible_claims": [
         "BrainCore",
-        "Enterprise memory lifecycle for AI agents",
-        "PostgreSQL + pgvector · CLI/MCP controls",
-        "v1.1.6"
+        "Evidence-first enterprise memory lifecycle for AI agents",
+        "PostgreSQL + pgvector · CLI/MCP controls · Open Source",
+        "v1.2",
+        "Governed memory",
+        "Audit trails",
+        "Traceable context",
+        "Evidence-first design"
       ]
     },
     {
       "path": "assets/lifecycle-control-flow.jpg",
       "status": "active",
       "usage": "README lifecycle control flow overview",
       "format": "JPEG",
-      "width": 1672,
+      "width": 1671,
       "height": 941,
-      "sha256": "13f5a1470d382d7658e10b09d58b17f96f61889e0de204483a5f7a11ae2c61e5",
+      "sha256": "016e990502245c50964d4923c69dbe4f507b3adfdedcce3718d92ff14d8d7184",
       "visible_claims": [
-        "Memory Lifecycle Control Flow",
-        "Recall audit, feedback, suppression, and retirement without destroying evidence",
-        "Retrieve",
-        "Inject",
-        "Omit",
+        "BrainCore v1.2 Memory Lifecycle Control Flow",
+        "Native evidence is preserved",
+        "Sources",
+        "Extraction",
+        "Facts",
+        "Review Queue",
+        "Approved Memory",
+        "Snapshot Retrieval",
+        "Prompt Package",
         "Feedback",
-        "Control",
-        "Active",
-        "Suppressed",
-        "Retired",
-        "Native evidence remains unchanged",
-        "Append-only archive",
-        "Source provenance",
-        "Immutable records"
+        "Suppression Overlay",
+        "Retirement Overlay",
+        "Audit Logs (Append-Only)"
       ]
     },
     {
       "path": "assets/architecture.jpg",
       "status": "active",
       "usage": "README architecture section",
       "format": "JPEG",
-      "width": 1672,
+      "width": 1671,
       "height": 941,
-      "sha256": "3d9766f0fdc7ac29aea9d7721d2dafb01d98cdc55b99ddec859a31d00862c8d3",
+      "sha256": "955d16e45d599ee3c0350af27ea6c66996dff7915243e5f4c7050f44a08ae065",
       "visible_claims": [
-        "BrainCore Architecture",
-        "Sources",
+        "BrainCore v1.2 Architecture",
+        "Ingest",
         "Archive",
         "Extract",
-        "Consolidate",
+        "Load",
+        "Review",
+        "Govern",
         "Retrieve",
-        "Publish",
-        "Hybrid Retrieval",
-        "SQL",
-        "Full-text",
-        "Vector",
-        "Temporal",
-        "Graph path",
-        "Evidence + Audit Guarantees",
-        "Append-only archive",
-        "Trust classes",
-        "Source provenance",
-        "Lifecycle audit trail"
+        "Audit",
+        "Source Ingestion",
+        "Durable Storage & Index Layer",
+        "Cross-Cutting Enablers",
+        "Audit & Lineage",
+        "Migration & Schema Management (v1.2)"
       ]
     },
     {

benchmarks/claims-to-evidence.yaml

@@ -272,20 +272,21 @@
     the single source of truth for the fusion k parameter. Source-tree
     invariant.
 
-- claim: "9 deterministic parsers"
+- claim: "12 deterministic source parsers"
   source: "src/extract"
   source_type: "file_lines"
   glob: "*-parser.ts"
-  expected: 9
+  expected: 12
   tolerance: 0
   framing: "smoke-regression"
   notes: >
     Counts files matching src/extract/*-parser.ts. Current set:
     asana-parser.ts, codex-parser.ts, codex-shared-parser.ts,
     discord-parser.ts, git-parser.ts, grafana-parser.ts,
-    personal-memory-parser.ts, session-parser.ts, telegram-parser.ts. deterministic.ts,
+    pai-auto-memory-parser.ts, personal-memory-parser.ts, project-doc-parser.ts,
+    session-parser.ts, telegram-parser.ts, vestige-parser.ts. deterministic.ts,
     semantic.ts, load.ts, project-resolver.ts, quality-gate.ts, verify.ts are
-    infrastructure files, not parsers. Source-tree invariant.
+    infrastructure files, not source parsers. Source-tree invariant.
 
 - claim: "PostgreSQL 15+ (tested on 16)"
   source: "benchmarks/README.md"

examples/mcp_server/requirements.txt

@@ -2,6 +2,6 @@ mcp[cli]>=1.27.1
 psycopg[binary]>=3.3.4
 psycopg-pool>=3.3.1
 pydantic>=2.13.4
-numpy>=2.4.5
+numpy>=2.4.6
 pgvector>=0.4.2
 requests>=2.34.2

examples/mcp_server/server.py

@@ -36,7 +36,9 @@
 from __future__ import annotations
 
 import importlib.util
+import json
 import os
+import subprocess
 import sys
 import types
 from pathlib import Path
@@ -257,6 +259,29 @@ def embed_query(text: str):  # noqa: ARG001  # signature match
 
 app = FastMCP("braincore-example-mcp")
 
+
+def _braincore_cli_command() -> list[str]:
+    raw = os.environ.get("BRAINCORE_CLI", "braincore")
+    return raw.split()
+
+
+def _run_braincore_cli(args: list[str]) -> dict[str, Any]:
+    command = [*_braincore_cli_command(), *args]
+    completed = subprocess.run(
+        command,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if completed.returncode != 0:
+        raise RuntimeError(completed.stderr.strip() or completed.stdout.strip() or f"BrainCore CLI exited {completed.returncode}")
+    output = completed.stdout.strip()
+    start = output.find("{")
+    if start == -1:
+        raise RuntimeError("BrainCore CLI did not return JSON output")
+    return json.loads(output[start:])
+
 # Deferred connection pool. Created on first tool invocation.
 _pool: Optional[ConnectionPool] = None
 
@@ -289,6 +314,41 @@ def _get_pool() -> ConnectionPool:
     return _pool
 
 
+@app.tool(name="braincore-snapshot")
+def braincore_snapshot_tool(
+    cwd: str,
+    git_root: Optional[str] = None,
+    prompt: Optional[str] = None,
+    mode: str = "shadow",
+    max_tokens: int = 3000,
+    limit: int = 20,
+) -> dict[str, Any]:
+    """Build an audited BrainCore memory snapshot through the BrainCore CLI.
+
+    This reference tool is intentionally read-only. It uses the same
+    ``braincore snapshot build`` surface operators use during runtime cutover.
+    Set ``BRAINCORE_CLI`` when the executable is not on PATH.
+    """
+    args = [
+        "snapshot",
+        "build",
+        "--cwd",
+        cwd,
+        "--mode",
+        mode,
+        "--max-tokens",
+        str(max_tokens),
+        "--limit",
+        str(limit),
+        "--json",
+    ]
+    if git_root:
+        args.extend(["--git-root", git_root])
+    if prompt:
+        args.extend(["--prompt", prompt])
+    return _run_braincore_cli(args)
+
+
 @app.tool(name="memory-search")
 def memory_search_tool(
     query: str,