Knowledge Intake

Table of Contents

• What It Is
• The Intake Signal
• Quick Start
• Evaluation Framework
• Importance Criteria
• Scoring Guide
• Application Routing
• Local Codebase Application
• Meta-Infrastructure Application
• Routing Decision Tree
• Storage Locations
• The Tidying Imperative (KonMari-Inspired)
• The Master Curator
• The Two Questions
• Tidying Actions
• Marginal Value Filtering (Anti-Pollution)
• The Three-Step Filter
• Using the Filter
• Filter Output Example
• Progressive Autonomy Integration
• RL-Based Quality Scoring
• Anchor-Question Clarity Gate
• Usage Signals
• Quality Decay Model
• Source Lineage Tracking
• Knowledge Orchestrator
• RL Integration with Marginal Value Filter
• Workflow Example
• Queue Processing
• Processing Queue Entries
• Queue Integration
• Queue Status Workflow
• Automation
• Detailed Resources
• Hook Integration
• Automatic Triggers
• Hook Signals
• Deduplication
• Safety Checks
• Index Schema Alignment
• Integration
• Exit Criteria

Knowledge Intake

Process external resources into the knowledge store. When a user links an article, blog post, or paper, this skill guides evaluation, storage decisions, and application routing.

When To Use

• Capturing and organizing knowledge from sessions
• Ingesting information into structured memory palaces

When NOT To Use

• Temporary notes that do not need long-term storage
• Code-only changes without knowledge capture needs

What It Is

A knowledge governance framework that answers three questions for every external resource: 1. Is it worth storing? - Evaluate signal-to-noise and relevance 2. Where does it apply? - Route to local codebase or meta-infrastructure 3. What does it displace? - Identify outdated knowledge to prune

The Intake Signal

When a user links an external resource, it is a signal of importance.

The act of sharing indicates the resource passed the user's own filter. Our job is to:

• Extract the essential patterns and insights
• Determine appropriate storage location and format
• Connect to existing knowledge structures
• Identify application opportunities

Quick Start

When a user shares a link:

1. FETCH    → Detect format, retrieve and convert content
2. EVALUATE → Apply importance criteria
3. DECIDE   → Storage location and application type
4. STORE    → Create structured knowledge entry
5. VALIDATE → Scribe verification (slop scan + doc verify)
6. CONNECT  → Link to existing palace structures
7. PROMOTE  → Offer Discussion promotion (score 80+)
8. APPLY    → Route to codebase or infrastructure updates
9. PRUNE    → Identify displaced/outdated knowledge

Step 1: FETCH with Format Detection

Before retrieving content, detect the source format from the URL or file path to choose the right retrieval method.

Web articles and blog posts (default path): Use WebFetch to retrieve HTML content directly. No conversion needed.

Document URLs (PDF, DOCX, PPTX, XLSX): Apply the leyline:document-conversion protocol. This tries the markitdown MCP tool first for high-quality markdown, then falls back to native Claude Code tools (Read for PDFs, etc.), then informs the user if the format is unsupported without markitdown.

Local files (user shares a file path): Construct a file:// URI from the absolute path and apply the leyline:document-conversion protocol.

Format detection heuristics:

After retrieval (regardless of method), wrap the content in external content boundary markers per leyline:content-sanitization before proceeding to Step 2 (EVALUATE).

Step 5: Scribe Validation (Required)

All knowledge corpus entries MUST pass scribe validation before finalizing.

Run Skill(scribe:slop-detector) on the new entry:

• Score must be < 2.5 (Clean to Light)
• No Tier 1 markers (delve, tapestry, comprehensive, leveraging, etc.)
• Hedge word density < 15 per 1000 words

Use Agent(scribe:doc-verifier) to validate:

• All file paths and URLs exist
• All cross-references valid
• Source attributions accurate

# Quick validation for knowledge corpus entry
/slop-scan docs/knowledge-corpus/[entry-name].md
# Doc verification is now agent-only:
Agent(scribe:doc-verifier) "Verify docs/knowledge-corpus/[entry-name].md"

DO NOT finalize entries with slop score > 2.5 - rewrite with concrete specifics. Verification: Run the command with --help flag to verify availability.

Step 7: Discussion Promotion (Score 80+ Only)

When the evaluation score is 80-100 (evergreen), you MUST execute the Discussion promotion workflow. If the score is below 80, skip this step entirely.

Execute these steps in order:

1. Read modules/discussion-promotion.md for the full GraphQL workflow 2. Tell the user: "This entry has reached evergreen maturity. Publishing to GitHub Discussions. [Y/n]" 3. If the user says "n", skip to Step 8 (APPLY) 4. Run the gh api graphql commands from the module to create or update a Discussion in the "Knowledge" category 5. Update the local corpus entry with discussion_url

• If the entry already has a discussion_url field,

update the existing Discussion instead of creating a new one

• If gh is unavailable or promotion fails, warn

the user and continue to Step 8 (APPLY)

Publishing is the default for qualifying entries. It never blocks the intake workflow.

Evaluation Framework

Importance Criteria

Scoring Guide

• 80-100: Evergreen knowledge, store prominently, apply immediately
• 60-79: Valuable insight, store in corpus, schedule application
• 40-59: Useful reference, store as seedling, revisit later
• Below 40: Low priority, capture key quote only or skip

Application Routing

Local Codebase Application

Apply when knowledge directly improves current project:

• Bug fix patterns
• Performance optimizations
• Architecture decisions for this codebase
• Tool/library recommendations

Action: Update code, add comments, create ADR

Meta-Infrastructure Application

Apply when knowledge improves our plugin ecosystem:

• Skill design patterns
• Agent behavior improvements
• Workflow optimizations
• Learning/evaluation methods (like Franklin Protocol)

Action: Update skills, create modules, enhance agents

Routing Decision Tree

**Verification:** Run the command with `--help` flag to verify availability.
Is the knowledge...
├── About HOW we build things? → Meta-infrastructure
│   ├── Skill patterns → Update abstract/memory-palace skills
│   ├── Learning methods → Add to knowledge-corpus
│   └── Tool techniques → Create new skill module
│
└── About WHAT we're building? → Local codebase
    ├── Domain knowledge → Store in project docs
    ├── Implementation patterns → Update code/architecture
    └── Bug/issue solutions → Apply fix, document

Verification: Run the command with --help flag to verify availability.

Storage Locations

The Tidying Imperative (KonMari-Inspired)

"A cluttered palace is a cluttered mind."

New knowledge often displaces old, but time is not the criterion. Relevance and aspirational alignment are.

The Master Curator

The human in the loop defines what stays. Before major tidying: 1. Who are you becoming? - Your aspirations as a developer 2. What excites you now? - Genuine enthusiasm, not "should" 3. What have you outgrown? - Past interests consciously left behind

The Two Questions

For each piece of knowledge, both must be yes:

• Does it spark joy? - Genuine enthusiasm, not obligation
• Does it serve your aspirations? - Aligned with who you're becoming

Tidying Actions

"I might need this someday" is fear, not joy. Release it.

Marginal Value Filtering (Anti-Pollution)

"If it can't teach something the existing corpus can't already teach → skip it."

Before storing ANY knowledge, run the marginal value filter to prevent corpus pollution.

The Three-Step Filter

1. Redundancy Check

• Exact match → REJECT immediately
• 80%+ overlap → REJECT as redundant
• 40-80% overlap → Evaluate delta (Step 2)
• <40% overlap → Likely novel, proceed to store

2. Delta Analysis (for partial overlap only)

• Novel insight/pattern → High value (0.7-0.9)
• Different framing only → Low value (0.2-0.4)
• More examples → Marginal value (0.4-0.6)
• Contradicts existing → Investigate (0.6-0.8)

3. Integration Decision

• Standalone: Novel content, no significant overlap
• Merge: Enhances existing entry with examples/details
• Replace: Supersedes outdated knowledge
• Skip: Insufficient marginal value

Using the Filter

from memory_palace.corpus import MarginalValueFilter

# Initialize filter with corpus and index directories
filter = MarginalValueFilter(
    corpus_dir="docs/knowledge-corpus",
    index_dir="docs/knowledge-corpus/indexes"
)

# Evaluate new content
redundancy, delta, integration = filter.evaluate_content(
    content=article_text,
    title="Structured Concurrency in Python",
    tags=["async", "concurrency", "python"]
)

# Get human-readable explanation
explanation = filter.explain_decision(redundancy, delta, integration)
print(explanation)

# Act on decision
if integration.decision == IntegrationDecision.SKIP:
    print(f"Skipping: {integration.rationale}")
elif integration.decision == IntegrationDecision.STANDALONE:
    # Store as new entry
    store_knowledge(content, title)
elif integration.decision == IntegrationDecision.MERGE:
    # Enhance existing entry
    enhance_entry(integration.target_entries[0], content)
elif integration.decision == IntegrationDecision.REPLACE:
    # Replace outdated entry
    replace_entry(integration.target_entries[0], content)

Verification: Run the command with --help flag to verify availability.

Filter Output Example

**Verification:** Run the command with `--help` flag to verify availability.
=== Marginal Value Assessment ===

Redundancy: partial
Overlap: 65%
Matches: async-patterns, python-concurrency
  - Partial overlap (65%) with 2 entries

Delta Type: novel_insight
Value Score: 75%
Teaching Delta: Introduces 8 new concepts
Novel aspects:
  + New concepts: structured, taskgroup, context-manager
  + New topics: Error Propagation, Resource Cleanup

Decision: STANDALONE
Confidence: 80%
Rationale: Novel insights justify standalone: Introduces 8 new concepts

Verification: Run the command with --help flag to verify availability.

Progressive Autonomy Integration

The marginal value filter respects autonomy levels (see plan Phase 4):

• Level 0: ALL decisions require human approval
• Level 1: Auto-approve 85+ scores in known domains
• Level 2: Auto-approve 70+ scores in known domains
• Level 3: Auto-approve 60+, auto-reject obvious noise

Current implementation: Level 0 (all human-in-the-loop).

RL-Based Quality Scoring

The knowledge corpus uses reinforcement learning signals to dynamically score entry quality based on actual usage patterns.

Anchor-Question Clarity Gate

Usage signals score an entry after it is stored, from how it gets accessed. They cannot catch a summary that was never clear enough to be useful. Before an entry is written, gate it on the MMPO dual-probe (arXiv:2605.30159), adapted from task state to knowledge value:

1. Value probe: what does this knowledge let us do? Name a concrete capability or decision it enables, not a topic label. 2. Gap probe: what does this knowledge not answer? List the bounded open questions it leaves, not generic "more research".

This gate is qualitative and complements, does not replace, the Importance Criteria score: a summary can score well on Applicability yet still fail the value probe if it cannot name what it enables. When memory-palace:memory-clarity-probe is installed, delegate the dual-probe evaluation to it and use its Recommendation as the gate.

Usage Signals

Quality Decay Model

Knowledge entries decay over time unless validated:

Entries are classified by decay status:

• Fresh: >70% quality retained
• Stale: 40-70% quality retained
• Critical: 20-40% quality retained
• Archived: <20% quality retained

Source Lineage Tracking

Hybrid lineage tracking based on source importance:

Full Lineage (for important sources):

• Primary source with complete metadata
• Derivation chain (what entries it was derived from)
• Transformation history (summarization, extraction, etc.)
• Validation chain (who validated and when)

Simple Lineage (for standard sources):

• Source type and URL
• Retrieval timestamp

Full lineage is used for:

• Research papers
• Documentation
• Entries with importance score >= 0.7

Knowledge Orchestrator

The KnowledgeOrchestrator coordinates all quality systems:

from memory_palace.corpus import KnowledgeOrchestrator, UsageSignal

# Initialize orchestrator
orchestrator = KnowledgeOrchestrator(
    corpus_dir="docs/knowledge-corpus",
    index_dir="docs/knowledge-corpus/indexes"
)

# Record usage events
orchestrator.record_usage("entry-1", UsageSignal.ACCESS)
orchestrator.record_usage("entry-1", UsageSignal.POSITIVE_FEEDBACK)

# Assess entry quality
entry = {"id": "entry-1", "maturity": "growing"}
assessment = orchestrator.assess_entry(entry)
print(f"Quality: {assessment.overall_score:.0%}")
print(f"Status: {assessment.status}")
print(f"Recommendations: {assessment.recommendations}")

# Get maintenance queue
entries = [...]  # Your entry list
queue = orchestrator.get_maintenance_queue(entries)
for item in queue:
    print(f"{item.entry_id}: {item.status} - {item.recommendations}")

# Ingest new content with lineage
from memory_palace.corpus import SourceReference, SourceType

source = SourceReference(
    source_id="src-1",
    source_type=SourceType.DOCUMENTATION,
    url="https://docs.example.com/api",
    title="API Documentation"
)
entry_id, decision = orchestrator.ingest_with_lineage(
    content="# API Reference\n...",
    title="API Documentation",
    source=source
)

Verification: Run the command with --help flag to verify availability.

RL Integration with Marginal Value Filter

The marginal value filter emits RL signals on integration decisions:

from memory_palace.corpus import MarginalValueFilter

filter = MarginalValueFilter(corpus_dir, index_dir)

# Evaluate with RL signal emission
redundancy, delta, integration, rl_signal = filter.evaluate_with_rl(
    content=article_text,
    title="New Article",
    tags=["python", "async"]
)

# RL signal contains:
# - signal_type: UsageSignal to emit
# - weight: Signal weight for scoring
# - action: What happened (new_entry_created, entry_enhanced, etc.)
# - decision: Integration decision made
# - confidence: Decision confidence
print(f"RL Signal: {rl_signal['action']} (weight: {rl_signal['weight']})")

Verification: Run the command with --help flag to verify availability.

Workflow Example

User shares: "Check out this article on structured concurrency"

intake:
  source: "https://example.com/structured-concurrency"

# PHASE 3: Marginal Value Filter
marginal_value:
  redundancy:
    level: partial_overlap
    overlap_score: 0.65
    matching_entries: [async-patterns, python-concurrency]
  delta:
    type: novel_insight
    value_score: 0.75
    novel_aspects: [structured, taskgroup, context-manager]
    teaching_delta: "Introduces structured concurrency pattern"
  integration:
    decision: standalone
    confidence: 0.80
    rationale: "Novel insights justify standalone entry"

# Continue with evaluation if filter passes
evaluation:
  novelty: 75        # New pattern for error handling
  applicability: 90  # Directly relevant to async code
  durability: 85     # Core concept, won't age quickly
  connectivity: 70   # Links to error handling, async patterns
  authority: 80      # Well-known author, cited sources
  total: 82          # Evergreen, store and apply

routing:
  type: both
  local_application:
    - Refactor async error handling in current project
    - Add structured concurrency pattern to codebase
  meta_application:
    - Create module in relevant skill
    - Add to knowledge-corpus as reference

storage:
  location: docs/knowledge-corpus/structured-concurrency.md
  format: memory_palace_entry
  maturity: growing

pruning:
  displaces:
    - Old async error patterns (mark deprecated)
  complements:
    - Existing error handling module
    - Async patterns documentation

Verification: Run the command with --help flag to verify availability.

Queue Processing

Research sessions and external content are automatically queued for review in docs/knowledge-corpus/queue/.

Processing Queue Entries

# List pending queue entries
ls -1t docs/knowledge-corpus/queue/*.yaml

# Review specific entry
cat docs/knowledge-corpus/queue/2025-12-31_topic.yaml

# Process approved entry
# 1. Create memory palace entry in docs/knowledge-corpus/
# 2. Update queue entry status to 'processed'
# 3. Archive or delete queue entry

Verification: Run the command with --help flag to verify availability.

Queue Integration

The research-queue-integration hook automatically queues:

• Brainstorming sessions with 3+ WebSearch calls
• Research-focused sessions with substantial findings
• Manual additions via queue entry creation

Queue entry format: See docs/knowledge-corpus/queue/README.md

Queue Status Workflow

**Verification:** Run the command with `--help` flag to verify availability.
pending_review → [Review] → approved/rejected
approved → [Create Entry] → processed
processed → [Archive] → queue/archive/

Verification: Run the command with --help flag to verify availability.

Automation

• Run uv run python scripts/intake_cli.py --candidate path/to/intake_candidate.json --auto-accept
• The CLI runs marginal value filter, creates palace entries (docs/knowledge-corpus/*.md),

developer drafts (docs/developer-drafts/), and appends audit rows to docs/curation-log.md.

• Use --output-root in tests or sandboxes to avoid mutating the main corpus.
• Queue Processing: Use --process-queue flag to review and process queued entries interactively.

Detailed Resources

• Evaluation Rubric: See modules/evaluation-rubric.md
• Storage Patterns: See modules/storage-patterns.md
• KonMari Tidying Philosophy: See modules/konmari-tidying.md
• Tidying Workflows: See modules/pruning-workflows.md
• Discussion Promotion: Invoked in Step 7 (PROMOTE)

for evergreen entries (score 80+). Publishing is the default action. See modules/discussion-promotion.md for full workflow.

Hook Integration

Memory-palace hooks automatically detect content that may need knowledge intake processing:

Automatic Triggers

Hook Signals

When hooks detect potential knowledge content, they add context messages:

**Verification:** Run `pytest -v` to verify tests pass.
Memory Palace: New web content fetched from {url}.
Consider running knowledge-intake to evaluate and store if valuable.

Verification: Run the command with --help flag to verify availability.

**Verification:** Run the command with `--help` flag to verify availability.
Memory Palace: Reading local knowledge doc '{path}'.
This path is configured for knowledge tracking.
Consider running knowledge-intake if this contains valuable reference material.

Verification: Run the command with --help flag to verify availability.

Deduplication

Hooks check the memory-palace-index.yaml to avoid redundant processing:

• Known URLs: "Content already indexed" - skip re-evaluation
• Changed content: "Content has changed" - suggest update
• New content: Full evaluation recommended

Safety Checks

Before signaling intake, hooks validate content:

• Size limits (default 500KB)
• Secret detection (API keys, credentials)
• Data bomb prevention (repetition, unicode bombs)
• Prompt injection sanitization

Index Schema Alignment

The deduplication index stores fields aligned with this skill's evaluation:

entries:
  "https://example.com/article":
    content_hash: "xxh:abc123..."
    stored_at: "docs/knowledge-corpus/article.md"
    importance_score: 82           # From evaluation framework, in [0, 100]
    maturity: "growing"            # seedling, growing, evergreen
    routing_type: "both"           # local, meta, both
    last_updated: "2025-12-06T..."

Verification: Run the command with --help flag to verify availability.

Integration

• memory-palace-architect - Structures stored knowledge spatially
• digital-garden-cultivator - Manages knowledge lifecycle
• knowledge-locator - Finds and retrieves stored knowledge
• skills-eval (abstract) - Evaluates meta-infrastructure updates
• memory-clarity-probe - Dual-probe gate for the clarity check above

Exit Criteria

• [ ] A non-2xx fetch is dropped, not stored: an HTTP 404/429 body

produces no index entry (enforced by web_research_handler)

• [ ] Every stored entry passed the anchor-question clarity gate: its

value probe names a concrete capability the knowledge enables

• [ ] Each stored entry has an importance_score in [0, 100] and a

routing decision from the Application Routing tree

• [ ] Entries scoring below 40 are captured as a quote or skipped, not

stored as full knowledge notes

• [ ] The index round-trips through its loader after intake

Discussion Promotion

Promote evergreen knowledge-corpus entries to GitHub Discussions for cross-session and cross-contributor discovery.

When This Module Applies

During the knowledge-librarian's review of corpus entries, when an entry has reached evergreen maturity in the digital garden lifecycle.

Eligibility Rules

Promote to Discussion

Step 1: Confirm Eligibility

Check the corpus entry's maturity field:

maturity: evergreen  # Required for promotion

If maturity is not evergreen, do not present the promotion option.

Step 2: Confirm Promotion (Default: Publish)

This entry has reached evergreen maturity. Publishing to GitHub Discussions. [Y/n]

Publishing is the default action. If the user explicitly declines ("n"), skip all subsequent steps.

Step 3: Resolve Repository and Category IDs

# Get repository node ID and "knowledge" category ID
gh api graphql -f query='
query($owner: String!, $repo: String!) {
  repository(owner: $owner, name: $repo) {
    id
    discussionCategories(first: 25) {
      nodes { id slug }
    }
  }
}' -f owner="OWNER" -f repo="REPO"

Find the category nodeID where slug equals "knowledge".

If the "Knowledge" category doesn't exist, warn and skip:

⚠ "Knowledge" discussion category not found. Skipping promotion.

Step 4: Create the Discussion

gh api graphql -f query='
mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
  createDiscussion(input: {
    repositoryId: $repoId,
    categoryId: $categoryId,
    title: $title,
    body: $body
  }) {
    discussion { number id url }
  }
}' -f repoId="$REPO_ID" -f categoryId="$CATEGORY_ID" \
   -f title="[Knowledge] $ENTRY_TITLE" \
   -f body="$BODY"

Title format: [Knowledge] <entry title>

Body structure (keep concise, link to local corpus for full details):

## Topic

<Entry title / topic>

## Summary

<Key points from the corpus entry — max 500 words>

## Source

<Original source URL or session reference>

## Tags

<Comma-separated tags from the entry>

---
*Maturity: Evergreen | Local corpus: `<relative path to corpus entry>`*
*Promoted from knowledge-corpus on YYYY-MM-DD*

Step 5: Apply Labels

Apply labels matching the entry's tags. Common labels:

• knowledge: always applied
• evergreen: always applied
• Entry-specific tags (e.g., graphql, python, architecture)

Step 6: Update Local Corpus Entry

Add a discussion_url field to the corpus entry:

discussion_url: https://github.com/OWNER/REPO/discussions/NUMBER
discussion_number: NUMBER
promoted_at: YYYY-MM-DDTHH:MM:SSZ

Update Discussion

When a corpus entry already has a discussion_url field (previously promoted), offer "Update Discussion" instead of "Promote":

This entry was previously promoted to Discussion #42. Updating it. [Y/n]

Update Flow

1. Extract the Discussion nodeID from discussion_url or discussion_number 2. Get the existing Discussion's nodeID:

gh api graphql -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    discussion(number: $number) { id }
  }
}' -f owner="OWNER" -f repo="REPO" -F number=$DISCUSSION_NUMBER

3. Update the Discussion body:

gh api graphql -f query='
mutation($discussionId: ID!, $body: String!) {
  updateDiscussion(input: {
    discussionId: $discussionId,
    body: $body
  }) {
    discussion { id url updatedAt }
  }
}' -f discussionId="$DISCUSSION_ID" -f body="$UPDATED_BODY"

4. Update the local corpus entry's promoted_at timestamp.

Token Conservation

• Discussion body: max 500 words (link to local file for full content)
• Do NOT duplicate the entire corpus entry: the Discussion is a summary

with a pointer

• Include the local file path so sessions can Read the full entry

Error Handling

• Network failure: Warn and skip. Do not block the knowledge review workflow.
• Missing category: Warn and skip.
• `gh` not authenticated: Skip with message about running gh auth login.
• Discussion already exists but can't be found: Create a new one and update the local reference.

Knowledge Evaluation Rubric

Systematic criteria for evaluating external resources and making storage decisions.

The Five Criteria

1. Novelty (25%)

Question: Does this introduce new patterns, concepts, or perspectives?

Signals of High Novelty:

• "I never thought of it that way"
• Connects previously unrelated domains
• Challenges existing assumptions
• Provides new vocabulary for existing concepts

2. Applicability (30%)

Question: Can we apply this to current or near-term work?

Signals of High Applicability:

• Addresses a known pain point
• Provides actionable steps
• Includes working examples
• Matches current technology stack

3. Durability (20%)

Question: Will this remain relevant in 6+ months?

Signals of High Durability:

• Focuses on principles over implementations
• Based on fundamental constraints
• Historical precedent of longevity
• Independent of specific tools/versions

4. Connectivity (15%)

Question: Does it connect to multiple existing concepts?

Signals of High Connectivity:

• Mentions concepts we already track
• Bridges different skill domains
• Creates "aha" moments about existing knowledge
• Enables cross-referencing

5. Authority (10%)

Question: Is the source credible and well-reasoned?

Signals of High Authority:

• Author has relevant experience
• Claims supported by evidence
• Acknowledges limitations
• Peer-reviewed or widely cited

Weighted Calculation

Total = (Novelty × 0.25) + (Applicability × 0.30) +
        (Durability × 0.20) + (Connectivity × 0.15) +
        (Authority × 0.10)

Decision Thresholds

Quick Evaluation Heuristic

For rapid assessment, ask: 1. Would I regret NOT storing this in 3 months? 2. Can I explain why this matters in one sentence? 3. Does it change how I think or work?

Yes to all 3 → Store as Evergreen Yes to 2 → Store as Valuable Yes to 1 → Store as Seedling No to all → Skip or Reference only

KonMari Tidying for Knowledge

Marie Kondo's philosophy adapted for knowledge curation. Time-based pruning is lazy governance. True tidying asks deeper questions: Does this knowledge still serve who you are becoming?

The Core Shift

"The question of what you want to own is actually the question of how you want to live your life."

(Marie Kondo)

Traditional pruning: "Delete if not accessed in 90 days" KonMari pruning: "Does this knowledge spark joy and serve your aspirations?"

Time is not the criterion. Alignment is.

Why This Matters for Code and Knowledge

A convoluted, polluted codebase causes harm to both home and mind:

• Mental clutter - Outdated patterns create cognitive noise
• Decision fatigue - Too many options paralyze action
• False confidence - Stale knowledge leads to wrong decisions
• Lost identity - You become what you keep, not what you accumulate

The memory palace is your intellectual home. Clutter in the palace is clutter in the mind.

The Six Rules Adapted

1. Commit to Tidying

Don't half-tidy. When you begin a knowledge review, complete it. Partial cleanup leaves worse mess than none.

2. Imagine Your Ideal Developer Life

Before pruning, ask: Who am I becoming?

• What kind of developer do I want to be in 1 year?
• What domains genuinely excite me?
• What have I outgrown?

Your aspirations define what stays.

3. Finish Discarding First

Don't reorganize before releasing. Moving cluttered knowledge to new locations hides clutter rather than tidying it.

4. Tidy by Category, Not Location

Review all knowledge of one type together:

• All architecture patterns at once
• All tool references at once
• All learning resources at once

This reveals true scope and redundancy.

5. Follow the Right Order

From easiest to hardest emotional attachment:

1. References - Tool docs, version notes (easiest to release) 2. Techniques - Patterns and practices 3. Insights - Lessons learned 4. Frameworks - Mental models and philosophies 5. Aspirational - Knowledge tied to identity (hardest)

Build decision-making muscle before confronting core beliefs.

6. Ask: Does It Spark Joy AND Serve Your Aspirations?

Two questions, both must be yes:

Does this spark joy?

• Pick up the knowledge (read it, hold it in mind)
• Do you feel "a little thrill, as if cells in your body are slowly rising"?
• Is there genuine enthusiasm, or just obligation?

Does this serve your aspirations?

• Does this align with who you're becoming?
• Would the developer you want to be use this?
• Does keeping it move you toward your goals?

The Curator's Prerogative

The human in the loop is the master curator. Your aspirations, your goals, and your vision of the future define relevance, not arbitrary metrics.

Only you can answer:

• What domains are you growing into?
• What have you consciously decided to leave behind?
• What knowledge represents your past self, not your future self?

Claude can prompt these questions. Claude cannot answer them for you.

The Joy Test for Knowledge

Hold the knowledge in your mind. Read a summary. Then feel:

"I might need this someday" is not joy. It's fear. Release with gratitude.

Releasing with Gratitude

When knowledge no longer serves you:

1. Acknowledge its contribution - "This pattern served me when I was learning X" 2. Thank it - Recognize its role in your development 3. Release it - Archive or delete, but consciously let go

This is not woo-woo sentiment. It's cognitive closure. Unprocessed releases create mental residue.

The Aspirational Alignment Check

For each piece of knowledge, map against your stated goals:

knowledge: "Legacy jQuery patterns"
aspirations:
  current_focus: "Modern React development"
  one_year_goal: "Full-stack TypeScript expertise"
  excitement: "Real-time collaborative apps"

alignment_check:
  serves_current_focus: false
  serves_one_year_goal: false
  sparks_genuine_excitement: false
  verdict: release_with_gratitude

When NOT to Release

Some knowledge resists tidying for good reason:

• Hard-won lessons from failure - Pain teaches; don't repeat it
• Foundational principles - Timeless truths transcend trends
• Counter-intuitive insights - Easy to forget, hard to relearn
• Context for decisions - "Why we DON'T do X" has value

Ask: "If I release this and need it later, can I easily reacquire it?"

• Yes → Safe to release
• No → Consider keeping despite low current relevance

The Tidying Prompt

When initiating a knowledge review, the curator should be asked:

1. Who are you becoming? Describe your aspirations as a developer. 2. What excites you right now? Not "should" - genuine excitement. 3. What have you outgrown? Past interests you've consciously left. 4. What would your ideal knowledge palace contain? Imagine it curated.

These answers become the filter for all subsequent decisions.

The Polluted Codebase Warning

A cluttered palace is a cluttered mind.

Signs your knowledge base needs KonMari tidying:

• Contradictory patterns for the same problem
• Knowledge you keep "just in case" but never use
• Outdated information creating confusion
• Difficulty finding what you actually need
• Feeling overwhelmed rather than empowered

When you notice these signs, SUGGEST tidying. Never act without curator approval.

The Curator Approval Requirement

CRITICAL: The master curator (human) must approve ALL tidying actions.

Claude's role:

• CAN: Detect signs of clutter, suggest reviews, prompt with questions, prepare options
• CANNOT: Archive, delete, deprecate, or modify knowledge autonomously

The approval flow:

Claude DETECTS  → Claude SUGGESTS  → Curator DECIDES  → Claude EXECUTES (only if approved)

This is not optional. The human's aspirations, context, and reasons may be invisible to Claude. What looks like clutter may serve purposes Claude cannot perceive.

Your palace. Your rules. Your approval required.

Sources

• About the KonMari Method
• Rule 6: Ask Yourself If It Sparks Joy
• Why the KonMari Method Works

Knowledge Tidying Workflows

KonMari-inspired approaches for curating the knowledge palace. The criterion is not time. It is alignment with who you are becoming.

"A cluttered palace is a cluttered mind."

Why Tidying Matters

A polluted knowledge base causes harm to both home and mind:

• Mental clutter - Outdated patterns create cognitive noise
• Decision paralysis - Too many options freeze action
• False confidence - Stale knowledge leads to wrong decisions
• Identity confusion - You become what you keep

The Master Curator

The human in the loop is the master curator. Your aspirations define what stays.

Before any tidying session, answer: 1. Who are you becoming? Your aspirations as a developer 2. What excites you now? Genuine enthusiasm, not "should" 3. What have you outgrown? Past interests consciously left behind 4. What would your ideal palace contain? Imagine it curated

These answers become the filter for all decisions.

Tidying Triggers

1. Intake-Triggered Tidying

When new knowledge arrives, ask:

• Does this supersede something existing?
• Does this contradict stored knowledge?
• Does the old knowledge still spark joy?

2. Feeling-Triggered Tidying

When you feel the weight of clutter:

• Difficulty finding what you need
• Overwhelmed rather than empowered
• Contradiction and confusion
• Don't wait for a schedule. Tidy now.

3. Aspirational Shift

When your goals evolve:

• New domain you're entering
• Old domain you're leaving
• Changed technology direction
• Evolved identity as a developer

The Tidying Order

From easiest to hardest emotional attachment:

1. References - Tool docs, version notes (easiest) 2. Techniques - Patterns and practices 3. Insights - Lessons learned 4. Frameworks - Mental models and philosophies 5. Aspirational - Knowledge tied to identity (hardest)

Build decision-making muscle before confronting core beliefs.

The Two Questions

For each piece of knowledge, both must be yes:

Does it spark joy?

• Hold the knowledge in mind
• Read it, feel your response
• Is there genuine enthusiasm or just obligation?

Does it serve your aspirations?

• Does this align with who you're becoming?
• Would the developer you want to be use this?
• Does keeping it move you toward your goals?

knowledge: "Legacy jQuery patterns"
aspirations:
  current_focus: "Modern React development"
  one_year_goal: "Full-stack TypeScript expertise"

alignment:
  sparks_joy: false
  serves_aspirations: false
  verdict: release_with_gratitude

Tidying Actions

Release with Gratitude

When knowledge no longer serves you: 1. Acknowledge its contribution 2. Thank it for its role in your development 3. Archive or delete consciously

This is cognitive closure rather than sentiment.

Archive

Historical reference, accessible but not prominent.

action: archive
gratitude: "This taught me the fundamentals of DOM manipulation"
reason: "No longer aligned with modern development focus"

Update

Refresh to align with current aspirations.

action: update
changes: ["Modernized examples", "Removed dated patterns"]

Merge

Consolidate fragmented knowledge.

action: merge
into: "primary-knowledge-entry.md"
preserved_insights: ["key point 1", "key point 2"]

What Resists Tidying

Some knowledge should stay even if rarely accessed:

• Hard-won lessons from failure - Pain teaches
• Foundational principles - Timeless truths
• Counter-intuitive insights - Hard to relearn
• "Why we don't" context - Explains decisions

Ask: "If I release this and need it later, can I easily reacquire it?"

• Yes → Safe to release
• No → Consider keeping

The Aspirational Alignment Check

tidying_session:
  curator_aspirations:
    current_focus: "[what you're building now]"
    one_year_vision: "[who you're becoming]"
    genuine_excitement: "[what truly energizes you]"
    consciously_leaving: "[what you've outgrown]"

  for_each_knowledge:
    sparks_joy: true/false
    serves_aspirations: true/false
    easily_reacquirable: true/false

    verdict:
      keep | update | archive | release

The Tidying Prompt

When initiating a knowledge review, Claude should ask:

"Before we tidy, tell me:

1. What kind of developer are you becoming?

2. What genuinely excites you right now?

3. What have you consciously decided to leave behind?

4. Imagine your ideal knowledge palace. What's in it?"

These answers guide all subsequent decisions. The curator's aspirations are the only valid filter.

Warning Signs: Suggest Tidying

• [ ] Contradictory patterns for the same problem
• [ ] Knowledge kept "just in case" but never used
• [ ] Outdated information creating confusion
• [ ] Difficulty finding what you actually need
• [ ] Feeling overwhelmed rather than empowered
• [ ] Knowledge that represents your past self, not future self

When you notice these signs, SUGGEST tidying to the curator. Never tidy autonomously.

The Curator Approval Requirement

CRITICAL: All tidying actions require explicit human approval.

Claude's role in tidying:

• CAN: Identify candidates for tidying, suggest actions, prompt with questions
• CANNOT: Archive, delete, deprecate, or modify knowledge without explicit approval

The Approval Flow

1. Claude DETECTS    → Signs of clutter or misalignment
2. Claude SUGGESTS   → "I notice X may no longer serve your aspirations. Would you like to review it?"
3. Curator DECIDES   → Human reviews and approves/rejects
4. Claude EXECUTES   → Only after explicit "yes, proceed"

Approval Prompts

When suggesting tidying:

I've noticed some knowledge that may warrant review:

- [item]: [reason it may no longer serve]
- [item]: [reason it may no longer serve]

Would you like to:
1. Review these together now?
2. Schedule a tidying session later?
3. Keep everything as-is for now?

This is your palace. You decide what stays.

Never Assume

Even with clear staleness indicators:

• Don't archive without asking
• Don't deprecate without approval
• Don't delete under any circumstances without explicit permission
• Don't assume the curator wants to tidy

The master curator may have reasons for keeping knowledge that Claude cannot perceive.

Sources

• KonMari Method
• Spark Joy Philosophy
• See also: modules/konmari-tidying.md for full philosophy

Knowledge Storage Patterns

Structured templates for storing different types of external knowledge.

Storage Location Matrix

Entry Templates

Full Palace Entry (Evergreen)

For high-value, durable knowledge:

---
title: [Descriptive Title]
source: [URL]
author: [Author name]
date_captured: [YYYY-MM-DD]
palace: [Thematic grouping]
district: [Subcategory]
maturity: evergreen
tags: [relevant, tags]
---

# [Title]

## Core Thesis
[1-2 sentences summarizing the main argument]

## Memory Palace Layout
[Spatial structure mapping key concepts]

## Key Concepts
[Detailed breakdown with sensory encoding]

## Connections
- Internal: [Links to skills/modules]
- External: [Related sources]

## Application Notes
[How to apply this knowledge]

## Source Attribution
[Full citation]

Technique Module (Skill Integration)

For patterns that enhance existing skills:

---
name: [technique-name]
description: [One line description]
category: techniques
tags: [relevant, tags]
dependencies: [parent-skill]
source: [URL]
complexity: beginner|intermediate|advanced
estimated_tokens: [number]
---

# [Technique Name]

## Origin
[Where this came from, attribution]

## The Pattern
[Core technique explanation]

## Application
[How to use it]

## Integration
[Links to related modules]

Quick Reference (Tool Knowledge)

For version-specific or tool-focused info:

---
title: [Tool/Library Name]
source: [URL]
date_captured: [YYYY-MM-DD]
version: [relevant version]
maturity: reference
expires: [optional expiry date]
---

# [Title]

## Quick Summary
[2-3 bullet points]

## Key Commands/Patterns
[Code examples]

## Gotchas
[Common pitfalls]

## See Also
[Related references]

Seedling (Lightweight Note)

For ideas to revisit:

---
title: [Brief Title]
source: [URL]
captured: [YYYY-MM-DD]
maturity: seedling
review_after: [YYYY-MM-DD]
---

## Key Insight
[One paragraph]

## Why It Matters
[One sentence]

## Next Action
[What to do with this]

File Naming Conventions

Maturity Progression

seedling → growing → evergreen → (archive)
    ↓         ↓          ↓           ↓
 1-2 weeks  1-3 months  permanent  deprecated

Promotion Criteria

Seedling → Growing:

• Accessed more than once
• Connected to other entries
• Expanded with new insights

Growing → Evergreen:

• Proven useful over 3+ months
• Stable, not frequently edited
• Well-connected in knowledge graph

Evergreen → Archive:

• Superseded by newer knowledge
• Technology/approach deprecated
• No longer applicable

Marginal Value Dual Output Prompt

Candidate Summary

• Title: {{title}}
• Source: {{source}}
• Palace / District: {{palace}} / {{district}}
• Tags: {{tags}}
• Autonomy Level: {{autonomy_level}}
• Curator: {{actor}}

Integration Decision

• Decision: {{integration_decision}}
• Confidence: {{integration_confidence}}

Intake Content

{{content}}