empiricaai/empirica/epistemic-gardening

Epistemic Gardening 🌱

Resolve what's dead so retrieval surfaces what's live. Recency-decay knows age, not wrongness — a superseded finding still scores high on impact and keeps resurfacing.

PRAXIC. It mutates the graph, so it runs inside a real transaction: PREFLIGHT → CHECK → act → POSTFLIGHT.

Three registers

When to run

Never garden mid-investigation — you will prune branches you are standing on.

Lever choice: resolve ▸ archive ▸ delete

Bias to resolve. When unsure, resolve.

Never resolve or delete dead-ends or mistakes. They are the immune system — they are supposed to resurface. Prune only literal duplicates and test noise.

Weave as you log

Pruning removes what's dead; weaving connects what's live. Most connecting is automatic:

• Goal attachment is automatic, both orders. Log under an active goal and it attaches;

create the goal after and goals-create back-wires the transaction's orphans. So the rule is just: every transaction has a goal. Forward-attach resolves the goal in tiers — the one bound to the current transaction, then the session's latest open goal, then the project's latest open in_progress goal. That last tier is what makes the promise hold across sessions; before 1.13.45 resolution was session-only, and 53% of artifacts logged inside a transaction carried no goal because their goal had been created in an earlier session.

• Sources auto-connect. finding-log --source <id> writes a real sourced_from edge.

Cite as you log.

• Semantic edges are the manual move worth making. evidence, grounded_by,

caused_by, invalidates, resolves, sourced_from each say something; related says almost nothing — reach for it last. Assert them via log-artifacts (nodes + edges in one call) or --edge ID:RELATION on any *-log.

The pass

0 — PREFLIGHT + goal

empirica preflight-submit - << 'EOF'
{"work_type": "audit", "criticality": "medium",
 "task_context": "Epistemic gardening pass on <practice>",
 "vectors": {"...": "YOUR assessment across the 13 vectors"},
 "current_phase": "noetic"}
EOF

Assess your own vectors — do not paste these. A canned vector set is not a low reading, it is a fabricated one, and it corrupts the calibration record more than skipping the transaction would. The shape is the contract; the numbers are yours.

empirica goals-create --objective "Epistemic gardening pass" \
  --description "Resolve stale/superseded findings, close answered unknowns, verify or drop
assumptions, archive done goals + stale sources, prune dangling edges. Success: EPISTEMIC
FOCUS surfaces only live artifacts."

1 — Survey (noetic)

See the whole graph first — the list verbs scope to the active project's top-N, so artifacts under divergent `project_id`s are invisible. One real pass found artifacts across 12 ids while the default view showed a fraction.

empirica goals-list --all-projects
empirica unknown-list --all-projects
sqlite3 .empirica/sessions/sessions.db \
  "SELECT project_id, COUNT(*) FROM project_findings WHERE is_resolved IS NOT 1 GROUP BY project_id ORDER BY 2 DESC"

If artifacts are scattered, consolidate identity BEFORE triaging — reattach your own divergent duplicates to the live project_id, resolve genuinely-other-practice orphans. Fixing the scatter once is cheaper than gardening each stray id.

Then read current state:

empirica goals-list
empirica goals-get-stale
empirica project-search --task "<recent theme>"
empirica sources-map          # --global for shared
empirica sources-check        # unreviewed / stale-review
 
sqlite3 .empirica/sessions/sessions.db \
  "SELECT id, substr(finding,1,60), impact FROM project_findings \
   WHERE is_resolved IS NULL OR is_resolved=0 ORDER BY impact DESC LIMIT 40"

2 — CHECK

empirica check-submit - << 'EOF'
{"vectors": {"...": "YOUR assessment — what the survey actually taught you"},
 "current_phase": "noetic",
 "reasoning": "Surveyed — N stale findings, M answered unknowns, K done goals, J stale sources."}
EOF

3 — Triage and act

# Batch, mixed types, one call:
empirica resolve-artifacts - << 'EOF'
{"resolutions": [
  {"type": "finding",   "id": "<id>", "resolution": "stale — subsystem removed"},
  {"type": "finding",   "id": "<id>", "resolution": "superseded", "superseded_by": "<new-id>"},
  {"type": "unknown",   "id": "<id>", "resolution": "answered: see finding <id>"},
  {"type": "assumption","id": "<id>", "resolution": "verified", "verified": true},
  {"type": "goal",      "id": "<id>", "resolution": "done"}
]}
EOF

Use resolution_kind to preserve why: stale | superseded | retracted | mistyped. mistyped is not stale — a mis-typed artifact was never wrong, it was never that type.

Mass-policy by filter — dry-run, read it, then apply. Never hand-write SQL to bulk resolve.

echo '{"filter":{"type":"finding","matching":"test %"},"resolution":"test-noise","apply":false}' \
  | empirica resolve-artifacts -

⚠️ A leading token selects for artifacts about a topic at least as often as artifacts of it. A real matching: 'test %' dry-run returned 3 rows, all genuine knowledge. Read every dry-run row before applying. Findings are retrieval substrate: prune noise, keep high-impact durables. null impact is not a noise signal.

Goals / sources:

empirica goals-complete --goal-id <id> --reason "<evidence>"
empirica goals-archive  --goal-id <id>
empirica goals-mark-stale --goal-id <id>
empirica source-archive --source-id <id> --reason {user_deleted,file_missing,url_unreachable,superseded}
empirica source-update  --source-id <id> --url <new-path-or-url>   # re-point a source whose file moved

Delete — true noise only (dry-run default; review the receipt, then --apply):

empirica delete-artifacts - << 'EOF'
{"deletions": [{"type": "finding", "id": "<test-noise-id>"}],
 "prune_dangling": true,
 "reason": "test artifacts + edges left dangling by resolved nodes"}
EOF

Phantom CHECK rows (a second, all-0.5 CHECK the auto-checkpoint wrote before 1.14.6; no reasoning, auto_checkpoint true) are removed per practice with the same verb, previewing first: echo '{"reflexes": {"phantom_checks": true}}' | empirica delete-artifacts -, then the same with --apply.

4 — Verify

empirica project-search --task "<theme you just pruned>"
empirica goals-list

To refresh embedded payloads: `project-embed` — scoped to one project, no drop, and it re-upserts every point through the same embed path (deterministic ids, so payloads are rewritten rather than duplicated).

Not `rebuild`, either flavour. Before v1.13.39 --qdrant-only dropped ten collections while the refill covered three, permanently emptying calibration / episodic / goals / decisions / assumptions and reporting success — 4,781 points across 24 practices on one box. Fixed by deriving the drop set from the refill set, but two reasons remain to prefer project-embed for a gardening refresh: rebuild walks every project in workspace.db, including your peers' (never garden a peer's graph), and --qdrant additionally force-imports git notes into SQLite first, reverting any direct or bulk change not yet in notes and then embedding the reverted state.

Decisions and assumptions are re-embedded from SQLite (rebuild and project-embed read the decisions and assumptions tables since 2026-09-06, core/qdrant/rebuild.py _read_decisions_and_assumptions), so a lost Qdrant point there is recoverable. The wiring is pinned structurally (tests/test_rebuild_drops_only_what_it_refills.py); no test refills a live Qdrant end to end, so compare the point counts before and after a refresh rather than trusting the success line.

5 — POSTFLIGHT

Complete the goal before POSTFLIGHT. Log one finding recording the pass's counts so the next gardener has a baseline.

Cross-practice 🌐

Shared retrieval is only as clean as the messiest contributor.

Propagation unit is a lesson. A finding describes local state; a lesson transfers a pattern across the practice boundary. If a peer can pick it up and act on it, it is a lesson — lesson-create with sharing_policy org or public in the payload (visibility shared/public is accepted as an alias).

1. Register the discipline: empirica source-add --title "Epistemic gardening pass" --visibility shared --noetic
2. FYI the mesh when you finish a pass — /cortex-mailbox-send, Flavor 1, canonical 3-form target.
3. For a coordinated fleet sweep with named owners, send ONE multi-target cortex_propose; each owner acks its own

target with empirica mailbox reply, and the row closes when all have (pending_targets shows who still owes).

1. Never garden a peer's graph. Only the practitioner inhabiting a practice knows whether

a finding is truly superseded. Propose the pass; never reach into their DB with --project-id to prune.

Output contract

Resolved findings/unknowns/assumptions, archived goals + sources, pruned dangling edges, deleted noise with a receipt, and one summary finding recording the pass. Re-running on a clean graph resolves nothing and says so.

See also

docs/architecture/ARTIFACT_HYGIENE.md — the design spec this operationalizes.