brain-artifact-miner
Extract, deconstruct, and synthesize operational skills, plan evolutions, and reusable scratch utilities from IDE brain artifact stores and streaming transcripts. Do not use for simple file listing or raw SQLite database mutations.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- brain-artifact-miner
- description
- Extract, deconstruct, and synthesize operational skills, plan evolutions, and reusable scratch utilities from IDE brain artifact stores and streaming transcripts. Do not use for simple file listing or raw SQLite database mutations.
02 资源文件 3
- 参考文档CARD.md5.7 KB
- 参考文档config.default.yaml288 B
- 脚本scripts/brain_artifact_miner.py7.4 KB
03 SKILL.md 正文
Brain Artifact Miner
brain-artifact-miner is the filesystem-native workspace archaeology and scratch utility salvage engine for autonomous coding agents. It extracts, deconstructs, and synthesizes operational skills, plan evolutions, and reusable scratch utilities from IDE brain artifact stores (C:\Users\spectre\.gemini\antigravity-ide\brain\) and streaming transcripts (transcript.jsonl / transcript_full.jsonl).
While conversations/*.db contains the relational SQLite database of step execution payloads (addressed by conversation-trajectory-miner), the brain/ directory constitutes the filesystem-native epistemic workspace: an orthogonal artifact tier capturing Python scratch tools, implementation plans, walkthrough documents, subprocess task logs, and untruncated model reasoning streams.
The miner executes an automated 5-stage mining progression across workspace artifact stores:
[1. Store Discovery & Boundary-Safe Handshake] → [2. Dual-Transcript & Artifact Topology Index] → [3. Scratch Tool Archaeology & Subprocess Task Triage] → [4. Dual-Lens Cognitive Bifurcation] → [5. Skill SDLC Validation & Knowledge Graph Commit]
See CARD.md for the companion summary card, prompt catalog, and verification rubrics. Consult book-to-skill-forge for literature-to-skill distillation and epistemic-memory-lifecycle for knowledge item promotion.
1. Store Discovery & Boundary-Safe Handshake
Enumerate, validate, and establish non-invasive connections to candidate conversation workspaces in the IDE brain store:
┌─────────────────────────────────────────────────────────────┐
│ BOUNDARY-RESILIENT HANDSHAKE PROTOCOL │
├─────────────────────────────────────────────────────────────┤
│ 1. Codec: sys.stdout.reconfigure(encoding='utf-8') │
│ 2. Safety: Pivot to non-modifying shell reads on denial. │
│ 3. Paging: Pipe commands with Out-File -Encoding utf8. │
│ 4. Fallback: Query relational steps when payloads restrict. │
│ 5. Inventory: Enumerate CIDs, mtimes, and artifact trees. │
└─────────────────────────────────────────────────────────────┘
- Configure Standard Streams:
- Reconfigure standard output and error streams to UTF-8 at module entrypoint to eliminate
cp1252encoding crashes on Unicode DAG symbols (Rule 23, Rule 50).
- Reconfigure standard output and error streams to UTF-8 at module entrypoint to eliminate
- Execute Non-Invasive Protection Fallback:
- When encountering IDE system protection boundary denials on
brain/<cid>/paths, pivot immediately to non-modifying shell reads (Get-Content,Get-ChildItem) or decoupled relational SQLite databases (conversations/<cid>.db, Rule 46) without stalling.
- When encountering IDE system protection boundary denials on
- Piping & Redirection Hygiene:
- Never rely on bare PowerShell
>redirects for machine-parsed logs; enforce UTF-8 streams viaOut-File -Encoding utf8or native subprocess piping to prevent UTF-16 LE BOM null-byte corruptions (Rule 26).
- Never rely on bare PowerShell
Consumes artifact: brain_workspace_directory Primary artifact: brain_manifest.json
Completion criterion: All target brain directories enumerated via UTF-8-safe shell reads, codec invariants initialized, zero protection boundary stalls, and zero bare > PowerShell redirects in any log-producing command.
2. Dual-Transcript & Artifact Topology Index
Extract and cross-link execution streams and strategic documents across gigabyte-scale session trees without memory exhaustion:
- Construct Binary Byte-Offset Seek Table:
- For multi-megabyte
transcript.jsonlandtranscript_full.jsonlfiles exceeding 10 MB, never load files line-by-line viaf.readlines()(Rule 48). - Scan the file once in binary mode (
open(..., 'rb')) to build an in-memory lookup table mappingstep_indexto(byte_offset, byte_length). - Execute all subsequent step retrievals via direct $O(1)$ random seeks (
f.seek(offset),f.read(length)).
- For multi-megabyte
- Dual-Transcript Synchronization & Truncation Dereference:
- Map compact
transcript.jsonlsteps to their untruncated reasoning counterparts intranscript_full.jsonlusingstep_indexas the join key (Rule 22). - When
is_truncated: trueis detected in a compact step, automatically dereference totranscript_full.jsonlto recover planner thoughts and raw tool arguments.
- Map compact
- Artifact Lifecycle Versioning & Null-Safe Metadata Parsing:
- Index
implementation_plan.md,walkthrough.md, andtask.mddocuments using bounded directory traversal (depth $\le 3$, Rule 52). - When parsing
.metadata.jsonsidecar files, extract optional collections viadict.get("key") or []to guard against explicit JSONnullvalues returningNone(Rule 33). - Compare initial plans against final walkthroughs to measure scope deltas and completion drift.
- Index
Consumes artifact: brain_manifest.json Primary artifact: artifact_topology_map.json
Completion criterion: O(1) byte-offset index built for all transcripts >10 MB; dual-transcript step cross-links established with is_truncated dereference logic; artifact lifecycle map constructed with null-safe sidecar parsing.
3. Scratch Tool Archaeology & Subprocess Task Triage
Catalog reusable domain utilities from ephemeral scratch folders and triage background process execution health:
| Category | File Archetype | Primary Role | Inspection Method |
| :--- | :--- | :--- | :--- |
| ast_and_lint | lint_*.py, check_*.py | Structural syntax verification | ast.parse & ast.walk |
| database_and_sql | db_*.py, query_*.py | Relational schema reflection | sqlite3 PRAGMA reflection |
| brief_and_visual | brief_*.py, visual_*.py | Standalone HTML generation | Regex doubled-brace checks |
| test_and_verify | test_*.py, verify_*.py | Characterization test contracts | pytest invocation patterns |
| search_and_grep | search_*.py, grep_*.py | Bounded pattern extraction | Regex token analysis |
| task_subprocesses | task-*.log | Subprocess exit triage | Stderr ring-buffer scan |
- AST-Based Scratch Tool Classification:
- Scan dormant Python scripts in
brain/<cid>/scratch/using bounded directory walks (depth $\le 3$, Rule 52). - Parse scripts via
ast.parseandast.walkto inspect functions, docstrings, and imports (Rule 42). Classify scripts into typed domain categories.
- Scan dormant Python scripts in
- Defensive Batch Exception Logging:
- Never use bare
except Exception: continuein batch scanning loops (Rule 32). - Log unexpected errors at
logger.warning(), and explicitly reraise programming errors (NameError,TypeError,AttributeError) so schema and import defects fail loudly.
- Never use bare
- Subprocess Stderr Drainage & Deadlock Triage:
- Ingest
.system_generated/tasks/task-*.logbackground task outputs. - Scan for non-zero exit codes, tracebacks, and proactor pipe buffer deadlocks.
- Maintain a bounded ring-buffer for stderr lines to surface failure diagnostics cleanly (Rule 53).
- Ingest
- F-String Template Hygiene:
- When synthesizing HTML visual briefs, ensure all CSS rules and regex syntax inside Python f-strings use doubled braces (
{{,}}) to prevent runtime string formatting crashes (Rule 51).
- When synthesizing HTML visual briefs, ensure all CSS rules and regex syntax inside Python f-strings use doubled braces (
Consumes artifact: artifact_topology_map.json Primary artifact: scratch_and_task_catalog.json
Completion criterion: >= 50 scripts classified across >= 4 categories; background task triage report emitted with non-zero exit code and deadlock signature counts; zero silent except: continue suppressions; zero bare > PowerShell redirects in log capture commands.
4. Dual-Lens Cognitive Bifurcation (Epistemic & Procedural)
Strictly bifurcate distilled artifact learnings into two complementary operational seams (Rule 41):
Consumes artifact: scratch_and_task_catalog.json Primary artifact: epistemic_procedural_spec.json
Completion criterion: Distillation strictly bifurcated into validated Knowledge Vault items with unbroken isnad lineage and executable skill scaffolds with zero-fork configuration.
4a. Epistemic Introspection Seam (Knowledge Vault)
- Extract verified heuristics, workspace topologies, and failure recovery invariants from artifact lifecycle drift and background task triage.
- Commit distilled items to the Knowledge Vault under
.harness/knowledge/<ki_id>/strictly adhering to the canonical dual-file directory format (metadata.json+summary.md, Rule 40). - Anchor every claim with unbroken isnad provenance citing primary conversation UUIDs, script paths, and transcript step indices.
4b. Procedural Skill Synthesis Seam (Agent Skill Scaffolding)
- Synthesize executable agent skills under
.agents/skills/<skill-name>/with structured 5-stage progression matrices. - Author companion summary cards (
CARD.md) with ASCII metadata boxes, stage tables, and mandatory invariant checklists using relative links (Rule 37, Rule 47). - Provide co-located
config.default.yamldefining baseline operational budgets (timeouts, token limits, retry bounds, Rule 44). - Implement modular, executable Python scripts in
scripts/using domain-prefixed names (brain_artifact_miner.py) to prevent globalsys.modulescollisions (Rule 57).
5. Skill SDLC Validation & Knowledge Graph Commit
Validate the synthesized artifacts against craft standards and index the capabilities into the runtime knowledge graph:
- Execute Diagnostic Craft Validation:
- Run
SkillValidator.validate()to assert complete compliance across structural, frontmatter, pillar, and card rules (Rule 34). - Evaluate boolean status via
report.validand inspect granular rule executions throughreport.checks(never check.passed). - Verify frontmatter description length (100–350 characters) with explicit negative boundaries (Rule 44).
- Ensure companion
CARD.mdutilizes single-pipe│borders and the exactSKILL: <name>tag (Rule 37).
- Run
- Index into Skill Knowledge Graph:
- Trigger
BuiltinSkillRegistryService.index_catalog()to register the new skill node and compute topological dependency edges (FEEDS,REQUIRES, Rule 35, Rule 55).
- Trigger
- Register in Context Map:
- Update
CONTEXT-MAP.mdunder the Agent Orchestration domain, defining explicit negative boundaries distinguishing from relational trajectory mining.
- Update
Consumes artifact: epistemic_procedural_spec.json Primary artifact: skill_validation_report.json
Completion criterion: Skill SDLC pipeline completes with valid status and zero warnings; skill indexed in knowledge graph with validated FEEDS edges.
The Three Foundational Pillars
Pillar I: The Visual Brief
Synthesize findings, artifact inventory heatmaps, and task log triage metrics into a self-contained HTML visual brief written to %TEMP%\brain-artifact-miner-<timestamp>.html (or /tmp/brain-artifact-miner-<timestamp>.html on Unix) loading Tailwind CSS and Mermaid.js via CDN. Present the absolute clickable path to the user for visual review.
Pillar II: The Mandatory Checkpoint
When proposing new skill creation, structural modifications, or epistemic knowledge commits, always author an implementation_plan.md artifact with RequestFeedback: true. The agent must STOP and wait for explicit human confirmation before executing mutating actions.
Pillar III: Explicit Anti-Patterns
Rigid behavioral boundaries must be maintained to prevent catastrophic failure modes.
Anti-Patterns
- Unbounded Directory Traversal — Executing unpruned recursive walks across 343 conversation directories causing pipe exhaustion and CPU thrash instead of depth-bounded traversal.
- Protection Boundary Stall — Halting or repeatedly failing when file tools encounter IDE system protection denials instead of pivoting immediately to non-modifying shell reads.
- Scratch Script Amnesia — Leaving valuable AST tools and diagnostic scripts dormant in dead conversation folders without cataloging or salvage.
- Silent Batch Exception Suppression — Using bare
except Exception: continuein batch scanning loops, masking missing imports and schema bugs as empty classification results. - Subprocess Pipe Deadlock Blindness — Ignoring background task stderr dumps and buffer locks in task logs instead of ring-buffered stderr drainage.
- Truncated Transcript Blindness — Relying solely on compact transcripts where model thoughts are truncated without auto-dereferencing to full transcripts.
- Generic Script Module Naming — Naming helper scripts with generic names like
miner.pythat pollutesys.modulesinstead of domain-prefixed naming. - Absolute URI Links in CARD.md — Using
file:///absolute paths in cross-skill references breaking portability across CI runners and container sandboxes. - JSON Null-Field Iteration Crash — Using
dict.get("key", [])when reading optional sidecar lists, crashing on explicit JSONnullvalues instead ofdict.get("key") or []. - Epistemic Seam Bypass — Scaffolding procedural skill files while failing to commit ground-truth isnad items to the Knowledge Vault.
- Unverified Skill Scaffolding — Committing skills without running
SkillValidatoror consuming reports viareport.validandreport.checks.
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.