knowledge

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)

1. Read .semantic/TAXONOMY.md to pick primary_tag, secondary tags, entity, and confidence.

2. 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 vocabulary
• supersedes / 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.