linxule/memex-plugin/garden-tending

Knowledge Garden Tending

Current State

Index: !sqlite3 "$(memex path --index 2>/dev/null)" "SELECT (SELECT COUNT(*) FROM fts_content) || ' docs, ' || (SELECT COUNT(*) FROM chunks) || ' chunks indexed'" 2>/dev/null || echo "(index unavailable)"

Condensation backlog (projects whose overview lags their memos — dated after condensed:, or more memos than memos_digested:): !memex check --condense 2>/dev/null | head -30 || echo "(memex CLI unavailable)"

Topic signal backlog (open ## Recent signals; closed sections and archived/redirect topics excluded): !memex check --signals 2>/dev/null | head -16 || echo "(memex CLI unavailable)" <!-- NOTE: !command` injections get slash-command argument substitution ($1, $2, $ARGUMENTS) applied BEFORE execution, so any $<digit>` in them is unsafe — keep shell logic in the CLI, not inline here. -->

Existing topics (use [[?name]] for anything NOT in this list): !ls $(memex path 2>/dev/null)/topics/*.md 2>/dev/null | xargs -I{} basename {} .md | sort | tr '\n' ' ' || echo "(no topics found)"

Path Setup

The memex CLI handles vault path resolution automatically. For Obsidian CLI and dreamer commands not yet wrapped, prefix with cd $(memex path 2>/dev/null) &&.

Core Principle

Memos are ore. Project overviews are metal. Topics are the connective tissue. Trails are the narrative arc. The vault is a living knowledge graph, not an archive. Garden tending is the practice of keeping it alive: distilling memos into overviews, connecting ideas across projects, pruning dead links, growing new topics where patterns emerge, and extending trails where understanding evolves.

The test: if someone starts a session in this project tomorrow, does the vault give them enough to pick up where things left off?

This is not about maintenance logs or summaries. It's about seeing the fuller picture — how does new knowledge relate to what's already here, how do we condense the whole thing and grow it into something more than the sum of its sessions?

The Garden Tending Lifecycle

Knowledge work in the memex follows a cycle:

1. Diagnose — Assess vault health, find what needs work (undigested memos, broken links, merge candidates, stale topics/trails)
2. Condense — Distill project memos into living _project.md overviews
3. Connect — Create cross-project topic notes where patterns emerge, add wikilinks
4. Crystallize — Analyze graph topology: which ghost nodes (unresolved links) should materialize as real topics?
5. Grow — Merge overlapping topics, expand stubs into full topics, extend trails
6. Maintain — Fix broken links, archive stale files, add aliases, improve discoverability

These aren't strict phases — they interleave. An agent condensing a project notices a cross-project pattern and creates a topic. The lead fixing wikilinks discovers a concept worth growing. Garden tending is sensing what the vault needs and responding.

For vault-wide work, use a team approach — human + Claude lead + Sonnet agents working in parallel. The human brings vision and priorities. Claude designs the team and reviews quality. Agents read and write. The vault grows.

Diagnosis: Mapping What Needs Work

When maintenance should act on the index itself, run the dreamer:

cd $(memex path 2>/dev/null) && uv run python -m memex.dreamer --scope=all --dry-run
cd $(memex path 2>/dev/null) && uv run python -m memex.dreamer --scope=project:<name> --dry-run

Use dry-run first (uses fast heuristics, no LLM calls). Without --dry-run, the dreamer uses Claude Sonnet via claude CLI for semantic deduction, contradiction detection, and pattern filtering — producing higher-quality insights suitable for quoting in project overviews. Falls back to heuristics if claude CLI is unavailable.

Before tending, build a map of what needs attention.

Option A: Run Synthesis First (Recommended for Large Vaults)

Run cross-session synthesis in a separate session (even a cheap Sonnet one):

memex search --since=2w "<pattern query>"

Read the results, then synthesize across them: look for recurring themes, contradictions between memos, projects with undigested work, and overlapping topics. The synthesis report identifies:

• Patterns across projects (topic candidates)
• Contradictions in understanding
• Projects with undigested memos
• Topics to merge (overlapping content)
• Compression candidates (superseded memos)

Bring that report to the garden tending session as input.

Option B: Quick Assessment

memex check --folders    # drifted project folders — consolidate BEFORE condensing (a condensed
                         # overview misses every memo still sitting in a fragment folder)
memex check --condense   # overviews lagging their memos: NEW (dated after condensed:), ARR (git-added after condensed: but older-dated — moved in), GAP (memos − memos_digested)
memex check --signals    # open Recent-signals per topic, closed-section-aware
memex session reconcile-orphans   # pending-memo signals: exact-covered vs genuine retries

--condense parses both memo filename formats (YYYY-MM-DD-slug and legacy YYYYMMDD-HHMM-slug) — a hand-rolled string compare sorts every legacy name as "newer" (2026-09-23: ~350 false "new" memos vs ~60 real). A substantial overview with no condensed:/memos_digested: shows as unstamped: stamp it, don't re-condense from scratch. GAP catches same-day memos and memos moved in by a consolidation.

Vault Health Check

# Comprehensive health report (uses native vault + alias commands)
cd $(memex path 2>/dev/null) && uv run scripts/obsidian_cli.py status
 
# Unresolved links (detailed)
cd $(memex path 2>/dev/null) && uv run scripts/obsidian_cli.py unresolved --verbose
 
# Orphans and dead-ends
cd $(memex path 2>/dev/null) && uv run scripts/obsidian_cli.py orphans --total
cd $(memex path 2>/dev/null) && uv run scripts/obsidian_cli.py deadends --total
 
# Alias coverage (for link resolution quality)
cd $(memex path 2>/dev/null) && uv run scripts/obsidian_cli.py aliases --total
 
# Crystallization readiness (alias-aware, with delta tracking)
memex check --tier ready
 
# Topic similarity (find merge candidates)
memex similarity                       # default threshold 0.85
memex similarity --threshold 0.90      # near-duplicates only
memex similarity --threshold 0.90 -v   # with file paths
 
# Auto-memory sync state (from Claude Code working memory)
memex sync --status

Auto-Memory Sync Check

Run memex sync --status to check for new or stale auto-memory files from ~/.claude/projects/*/memory/. Sync before tending to ensure current project knowledge is in the vault. After syncing new files, add wikilinks in the ## Vault Annotations section to connect them to the knowledge graph. Files with volatile: true (MEMORY.md) change frequently — don't treat as stable references for condensation.

Interpretation:

• 5+ NEW memos (memex check --condense) → needs condensation
• `unstamped` (substantial overview, no `condensed:`/`memos_digested:`) → NOT never-condensed; the overview is current but predates the frontmatter convention (or was hand-written). Just add condensed:/memos_digested: frontmatter — don't re-condense from scratch. Distinguishing this from a true stub avoids wasted re-condensation work.
• Empty `_project.md` → condensation overdue
• High unresolved link count → needs link fixing (but clean frontmatter noise first)
• Orphans → isolated notes that need connecting
• Dead-ends → notes with no outbound links (should link to topics)
• Similarity > 0.90 → likely duplicates, merge or alias one to the other
• Similarity 0.85-0.90 → related but may be distinct, review manually

Clean noise before measuring. Frontmatter artifacts, transcript URLs, and template references inflate unresolved counts. Fix these first to see the real signal. In practice, 512 "unresolved" links became 356 after frontmatter cleanup — a 30% reduction before agents even started.

Suggested Concept Frequency

Preferred: Use crystallization check (alias-aware, with maturation tiers and delta tracking):

memex check              # full report
memex check --tier ready  # actionable items only
memex check -v            # with source files

Fallback: grep for `[[?concept]]` placeholders:

grep -rh '\[\[?' $(memex path 2>/dev/null)/projects/ 2>/dev/null | \
  grep -o '\[\[?[^]]*\]\]' | \
  sed 's/\[\[?//;s/\]\]//' | \
  sort | uniq -c | sort -rn | head -20

Concepts mentioned 3+ times across projects are strong candidates for topic creation.

Health Report Format

When presenting diagnosis results, use this tabular format:

Condensation: Distilling Memos into Overviews

Condensation compresses along the time axis — many sessions become one overview. This is distinct from crystallization (which works the topology axis) and connection (which grows cross-project patterns).

When to Condense

• 1-4 new memos: Not worth re-condensing unless they change the architecture
• 5+ new memos: Worth updating — read the new ones, revise the overview
• Major architectural change: Update immediately regardless of count
• Never condensed: First condensation is the biggest lift, but most valuable

For projects with 10+ memos, spawn an Explore agent to read them all and extract: dates, key decisions, what's superseded, what's still active, open threads. For smaller projects, read directly.

The Process

1. List Existing Topics First

This is the most common source of errors — linking to topics that don't exist without the [[?...]] prefix.

ls $(memex path 2>/dev/null)/topics/*.md | xargs -I{} basename {} .md | sort

Store this list. You'll need it for every wikilink you write. If assigning to an agent, include the topic list in their prompt.

2. Read Current _project.md

Check what's there already. If it has a condensed date in frontmatter, focus on memos since that date. If empty, read all memos.

3. Read Project Memos

ls -t $(memex path 2>/dev/null)/projects/<name>/memos/*.md

For team-based condensation, assign 2-4 projects per agent, grouped by domain affinity (philosophical projects together, tool projects together). An agent that condenses one project in a domain builds context that helps it condense the next.

4. Write the Overview

Use this format:

---
type: project
name: <project>
created: <original date>
condensed: <today>
memos_digested: <count>
---
 
# Project Name
 
[1-2 sentences: what is this project? Link to relevant [[topics]].]
 
Workspace: `<path>`
 
## Current Architecture
 
[How the system works right now. Link to [[topic-notes]] for detailed subsystems. This section is the most valuable — it's what memos can't give you because each memo only sees one session.]
 
## Key Decisions in Effect
 
| Decision | Why | Date |
|----------|-----|------|
| [Active decision] | [Rationale, not just "it's better"] | [When decided] |
 
[Only decisions that are STILL in effect. Superseded decisions are history — omit unless the supersession itself is a lesson.]
 
## What's Been Learned
 
[Hard-won lessons organized by area. The gotchas, the non-obvious, the things that bit you. Link to [[topics]] for the concepts behind the lessons.]
 
## What's Active
 
[Current work in progress. What shipped recently. What's being explored.]