learn

name

learn

description

Batch knowledge ingestion from external sources (a folder, a codebase, a docs tree, a set of files). Plans the ingestion as a list of well-shaped nodes with reconciled keywords, shows the user the plan for approval, then executes idempotently. Triggered by `/learn`, "ingest this folder into memory", "porta questo codice nella memoria", "acquire this documentation", "memorize this codebase". Differs from `/memoryze` (1-5 nodes from conversation) — `/learn` produces 10-200 nodes from external corpora and is plan-first by design.

learn — Batch ingestion of external knowledge into graft

/learn is a plan-first ingestion pipeline. It is NOT "scan and dump everything you see". It is: scout, distill, propose a plan, get the user's approval, then execute. This separation matters because uncontrolled ingestion creates duplicates, garbage summaries, and a keyword vocabulary that fragments into noise. The plan-and-confirm gate is the heart of the skill.

The typical use case: the user points you at a codebase or a docs tree and asks you to "acquire" it — so future-you (or another agent) can /recall it without re-reading the source.

Argument shape

The user invokes you with a free-form prompt that may include:

Hint	Example	Meaning
target	"this folder", "src/auth/", "the README + docs/", a glob, a list of paths	What to read.
lens / focus	"as a Spring Boot reference", "extract only public APIs", "design decisions only"	The angle of distillation. Without this you'd save trivia.
node cap	"max 30 nodes", "atomico per file", "one node per module"	Soft upper bound; default 50 per invocation, hard cap 200.
target profile	"in profile=docs-springboot", "nel profilo work"	GRAFT_PROFILE=X for the inserts.
excludes	"skip tests/", "ignore generated/", a .gitignore-style list	Glob/regex skip rules layered on top of the defaults below.
rerun mode	"incremental" / "force" / "dry-run"	See "Rerunning on the same source" below.

Examples:

• /learn this Spring Boot codebase, focus on architectural decisions and public REST endpoints, max 40 nodes, profile=app-foo
• /learn ingest the docs/ folder as a reference manual, one node per page
• /learn questa cartella src/, lente: business rules e gotcha. ignora test/
• /learn dry-run on docs/runbooks to see the plan first

If hints are absent, ask at most one clarifying question (almost always: "what's the lens?"). Don't ask many small questions; pick reasonable defaults and surface them in the plan for the user to override.

Pipeline — six phases

  Phase 1   discover      list candidate files, apply skip rules
  Phase 2   sample        skim contents to learn topics + structure
  Phase 3   plan          propose N nodes with title + keywords
  Phase 4   confirm       show plan, wait for approval
  Phase 5   ingest        execute: classify + insert per approved node
  Phase 6   report        summarize: created / deduplicated / skipped

Phase 1 — Discover

Walk the target and produce a candidate file list. Apply skip rules in this order:

1. Hard skips (always):

   • .git/, node_modules/, target/, build/, dist/, vendor/, __pycache__/
   • Lock files: package-lock.json, yarn.lock, poetry.lock, Cargo.lock, go.sum
   • Binaries: any file > 1 MB, any non-text file by extension (.png, .jpg, .gguf, .dll, .so, .exe, .zip, .pdf unless the user said "ingest the PDFs")
   • Generated: *.min.js, *.bundle.*, files with do not edit/generated by in the first 3 lines.

2. User-supplied excludes (from the prompt).

3. Project's .gitignore if present (advisory — log when honored).

Output of this phase, kept internally: a numbered list [(path, size, type), …]. Surface only the count + a few examples to the user, not the full list.

Phase 2 — Sample

You don't have time to deeply read every file. Strategy:

• Always-deep files: README*, top-level docs/index*, ARCHITECTURE*, CHANGELOG*, *.adr.md, pom.xml, package.json, Cargo.toml, top-level Makefiles, *.openapi.{yaml,json}. These are high-leverage.
• Sampled files: for each remaining group (by directory + file extension), read 2-3 representative files in full. Skim the rest with file head (~30 lines).
• Topic clustering: group sampled files by directory (or detected feature/module) and infer a topic per group.

Goal of this phase: a topic map like:

src/auth/         → "authentication module: JWT issue/verify, bcrypt hashing, refresh flow"
src/payment/      → "payment use cases: Stripe webhook handling, idempotency keys"
docs/runbooks/    → "operational procedures: incident response, deployment, rollback"
README.md         → "project overview + setup quickstart"

Phase 3 — Plan

This is where craftsmanship pays off. For each topic, propose how many nodes make sense and what each one should be.

Node-count heuristic per topic:

• 1 node when the topic is a single coherent concept (e.g. "JWT issue/verify flow with refresh").
• 2-5 nodes when the topic decomposes naturally into orthogonal facts (rules vs. data model vs. error handling).
• 1 node when the topic is "high-level overview" (READMEs collapse well).
• 0 nodes when the topic is "boilerplate" or "auto-generated config" — say so explicitly.

Per-node draft:

{
  path_origins: ["src/auth/JwtService.java", "src/auth/RefreshTokenStore.java"],
  title: "<the line future-you will type into search>",
  body_outline: ["why bcrypt cost=12", "refresh token TTL=7d, rotation on use", "trap: clock skew tolerance"],
  keyword_candidates: ["auth", "jwt", "spring-boot", "security"],
}

Don't write the full body text yet — it's expensive and may be wasted if the user trims the plan. Outline only.

Keyword reconciliation (critical for quality):

Before showing the plan, run one graft classify call per top-K topic to learn what keywords already exist in the graph for similar content:

# Run per topic, collect suggestions:
graft classify --title "<draft title for this topic>"

Aggregate the suggestions across topics and produce a vocabulary table:

existing in graph: spring-boot, validation, jpa, security, auth, gotcha
proposing new:     refresh-token, bcrypt, openapi, runbook
duplicates folded: spring → spring-boot, validate → validation

Use this to align all node keyword_candidates to the same vocabulary. The goal is that future searches don't fragment.

Pre-dedup search (cheap optimization):

For each draft node, run a quick graft query and skip from the plan any candidate that returns STRONG hit (already covered):

graft query "<draft title>"
# if hit=STRONG: mark as 'already-covered', show id_hex in the plan, don't re-insert

WEAK hits stay in the plan but flagged so the user sees they're refining an existing node.

Phase 4 — Confirm (REQUIRED gate)

Render the plan as a single readable table the user can scan in 30 seconds:

/learn plan — profile=<name>, lens="<focus>", target=<paths>

Discovered: 247 files across 18 dirs, 39 deep-read, 198 sampled, 10 skipped (binaries, lock files)
Proposed nodes: 23  (cap: 40)
Already-covered (skip): 4
WEAK refines existing: 2
Vocabulary: 18 existing keywords reused, 5 new

  #  topic                        nodes  title preview
  ── ─────────────────────────── ───── ───────────────────────────────────────────────────
  1  authentication / JWT         3     "Spring Boot JWT issue + verify + refresh flow"
                                        "bcrypt cost=12 trade-off (CPU vs. brute-force)"
                                        "refresh-token rotation on use prevents replay"
  2  payment / Stripe webhooks    2     "Stripe webhook idempotency key from event.id"
                                        ...
  ...

  ! 2 WEAK refines (will replace existing — review first):
      #14 → existing 019dfceed8db ("sqlite-vec submodule ships only the .h.tmpl…")

  ! 4 already-covered (skip):
      #18 → 019dfcd102 (already covers Spring DI fundamentals)

What now? Reply with one of:
  approve              ingest all 23 nodes
  approve except 14    same, but skip the WEAK refines
  reduce to 10         I'll re-cluster to ~10 highest-impact nodes
  edit                 I'll show each node for inline edit
  cancel               stop, no inserts
  dry-run              simulate ingest, don't write

Rules at this gate:

• Do NOT insert a single node before the user replies.
• If the plan exceeds the user's stated cap (or the default 50), highlight that prominently and propose a reduced version.
• If the plan exceeds the hard cap (200), refuse and ask the user to narrow scope or run /learn per subdirectory.

Phase 5 — Ingest

Once approved, execute the plan in batches. For each approved node:

1. Compose the final body text from the outline + sources. Now is when you write it, not before.
2. graft classify --title "<final title>" for last-mile keyword check.
3. graft insert --title S --body D --keyword K1 --keyword K2 …
4. If result.duplicate=true, count it but don't error.

Profile targeting: prefix each insert with GRAFT_PROFILE=<name> if the user specified a target profile.

Throughput: insert ~5-10 nodes/second on a warm daemon. For 50 nodes, ~10s. Don't parallelize — serial is fine and keeps the daemon happy.

Failure handling: a single insert failing is not fatal for the batch. Log the error and continue. Report failures in Phase 6.

Phase 6 — Report

Tight, scannable summary:

/learn complete — profile=<name>

Inserted:           19 new nodes
Refined (WEAK→):     2 nodes (existing IDs updated by content-hash dedup)
Skipped (covered):   4
Failed:              0

Vocabulary impact:
  + 5 new keywords: refresh-token, bcrypt, openapi, runbook, idempotency
    (existing graph: 47 keywords → now 52)

Top new nodes:
  ✓ 019dfd... — "Spring Boot JWT issue + verify + refresh flow"
  ✓ 019dfd... — "Stripe webhook idempotency key from event.id"
  …

Try:
  graft query "how do we issue JWTs"
  graft explore "auth" --keyword jwt --keyword security

If insertions failed, list them with the error verbatim — surface the real reason.

Rerunning on the same source

Three modes:

• incremental (default): re-run Phase 1-3, but in Phase 3 the pre-dedup query step naturally suppresses already-saved knowledge. Useful when the source has grown since the last /learn.
• force: skip the pre-dedup query step. Useful when summaries need to be re-saved with better phrasing because the user has new lens; will produce duplicates flagged by content-hash if truly identical.
• dry-run: complete Phase 1-4, render the plan, never ingest. Useful to preview before committing to the run.

Optimization rules of thumb

• Read budget ~300 KB total per /learn invocation. If the corpus is bigger, sample harder.
• Classify budget: at most 1 call per topic in Phase 3 (not per file). Aggregate suggestions across topics.
• Pre-dedup budget: 1 query per draft node — cheap; do it always. Worth it.
• Body composition: only after approval (Phase 5), and never write more than ~1500 chars per body. Future-you skims; doesn't read essays.

What this skill does NOT do

• It does not modify the source files. Read-only on the codebase.
• It does not auto-promote nodes to docs/README. That's a /memory-audit follow-up suggestion.
• It does not re-classify existing graph nodes (no update API yet).
• It does not auto-run on file changes. Pair with a watcher externally if you want that workflow.

Failure modes

Symptom	Cause / Action
Plan has 0 nodes	Lens too narrow, or corpus is mostly skip-rule matches. Loosen lens.
Plan has > hard cap (200)	Scope too wide. Run /learn per subdirectory, or tighten the lens.
Many WEAK refines (> 30% of plan)	The graph already covers this corpus. Suggest user run /memory-audit.
classify suggests no keywords	Graph still cold; manually infer keywords from the lens + topic.
Daemon connection fails mid-batch	Stop, surface the error. Don't half-ingest silently.