| name | knowledge |
| description | Canonical build-loop-memory framework. Use when the user asks to "record a decision", "log an ADR", "write an MADR", "capture this choice", "regenerate the decisions index", "validate knowledge", "migrate feedback to decisions", or "recall <topic>". ALSO the read-only review surface (review mode): "review my decisions", "show review queue", "check decision rot", "list open conflicts", "find stale procedures", or `/knowledge:review`. Active durable writes go to `~/dev/git-folder/build-loop-memory`; legacy `.episodic/` paths are migration/archive inputs only. |
Knowledge — Canonical Build-Loop Memory (Phases 1 + 2)
This skill is the entrypoint for the four-memory-types framework. The
full design lives at
~/dev/research/topics/repo-episodic-memory-framework/repo-episodic-memory-framework.md
(see §11–§14 for the four-memory-type taxonomy, extraction pipeline,
and Postgres schema). Read it before making structural changes.
What lives where
~/dev/git-folder/build-loop-memory/
├── projects/<project>/decisions/ # canonical MADR decisions + INDEX.md
├── projects/<project>/lessons/ # project-specific lessons
├── lessons/ # cross-project lessons
├── indexes/ # generated canonical indexes
└── db/ # Postgres helper material
<repo>/.build-loop/events.jsonl # repo-local runtime timeline
<repo>/.episodic/ # legacy migration/archive input only
Phase 1 surface — file-only operations
| Need | Tool |
|---|
| Write a decision (file only) | python3 scripts/write_decision/__main__.py … |
| Validate frontmatter + links | python3 scripts/validate_knowledge.py … |
| Regenerate INDEX files | python3 scripts/regenerate_knowledge_index.py … |
Migrate feedback.md to MADR | python3 scripts/migrate_feedback_to_decisions.py … |
| Migrate playbooks to procedural | python3 scripts/migrate_playbooks_to_procedural.py … |
Phase 2 surface — DB-backed retrieval
write_decision.py dual-writes (file canonical + best-effort DB row +
embedding via embed_backend). DB errors do NOT fail the file write — the DB
is regenerable from files.
| Need | Tool |
|---|
| Initialize schema | psql -d agent_memory -f scripts/init_agent_memory_schema.sql |
| Recall decisions on a topic | python3 scripts/recall.py --query "…" --limit 5 … |
| Rebuild DB from canonical files | python3 scripts/sync_db_from_files.py --rebuild |
recall.py is the entry point for Phase 1 Assess to load only the most
relevant prior memory rather than reading INDEX.md wholesale. See
references/recall-integration.md.
Authoring a decision (manual)
-
Read .semantic/TAXONOMY.md to pick primary_tag, secondary
tags, entity, and confidence.
-
Run write_decision.py with the required flags. The script:
- Allocates the next sequential ID (zero-padded 4-digit).
- Writes the MADR to
~/dev/git-folder/build-loop-memory/projects/<project>/decisions/<canonical-id>.md using
skills/knowledge/templates/madr-minimal.md as the body
scaffold (filled from CLI flags).
- Regenerates the canonical decisions
INDEX.md.
- Appends one event to
<repo>/.build-loop/events.jsonl.
- Embeds the body via local Ollama and inserts a row into
agent_memory.<schema>.semantic_facts (best-effort; file
write succeeds even if DB is down).
File writes are atomic (lock + tempfile + replace).
Topic identity & overwrite rules
primary_tag + entity is the topic-identity key. Two decisions sharing
both fields describe the same topic; the writer enforces the
overwrite ladder defined in TAXONOMY.md §3:
- Higher confidence auto-supersedes lower (no flag needed).
- Equal confidence requires
--supersedes <id> (explicit user direction).
- Lower confidence cannot displace higher.
Superseded decisions move to _history/<id>-v<N>.md; INDEX shows only
the current version.
Validation
validate_knowledge.py checks:
- Frontmatter shape (required keys, value types, enum membership)
tags and primary_tag against TAXONOMY's vocabularysupersedes / superseded_by links resolve to existing files
write_decision.py calls the validator as a pre-write gate; you can
also run it standalone over the whole tree.
Postgres connection
DB-side scripts read connection from
~/.config/agent-memory/connection.env (DATABASE_URL=
postgresql://tyroneross@localhost:5432/agent_memory). Per-project schema:
this repo uses build_loop_memory. The schema name is configurable via
the --schema flag on each DB-aware script.
Review mode (read-only)
The read-only review surface — /knowledge:review and asks like "review my
decisions", "show review queue", "check decision rot", "list open conflicts",
"find stale procedures" — lists the four sections of decisions/procedures
awaiting human attention (review queue, decision rot, open conflicts, stale
procedures) with a suggested action per item. It NEVER auto-resolves; humans
take the action. Full surface, invocation flags, and the consolidation
cross-reference: references/review-mode.md. (Namespace note: this surface
reviews the legacy .episodic/ paths; active durable writes target
build-loop-memory canonical.)
What's NOT in this skill
- Auto-capture from conversation — Phase 3 (
auto-decision-capture
skill, Stop hook with scan_transcript_for_decisions.py)
- Memory consolidation — Phase 4 (
consolidate_memory.py)
derived/libraries.json and derived/CHANGELOG.md generators —
Phase 1.5 / 4
Use this skill only for Phase 1 (manual + scripted) and Phase 2
(retrieval) operations.
