This tutorial walks through one complete session cycle: resuming context, capturing knowledge, and handing off to the next session. By the end, you'll have working muscle memory of the core lifecycle.
Time: 15 minutes
Verify Lore is installed:
lore --helpYou should see the command list. If not, see the README for installation.
Every session begins with resume. This loads context from the previous session -- what was done, what's next, what's blocked.
lore resumeIf this is your first session, you'll see minimal output. That's fine -- there's no history yet.
If there's prior history, you'll see:
- What was accomplished -- goals addressed, decisions made
- Patterns learned -- lessons captured from previous work
- Handoff notes -- next steps, blockers, open questions
Key point: Resume is read-only. It seeds your context without touching the historical record. Pass --fork to create a new session that inherits this context.
You noticed something worth remembering but don't yet know what it means. Capture it as an observation -- the lowest-friction write.
lore capture "Users frequently ask about retry logic"Bare capture creates an observation in the inbox. No classification required. Promote observations to decisions or patterns later when a clear pattern emerges.
With tags:
lore capture "API latency spikes during deploys" --tags "infra,performance"You've made a technical decision. Add --rationale to signal importance and route to the journal.
lore capture "Use PostgreSQL for user data" --rationale "Need ACID transactions, team has Postgres experience"The decision goes into the journal. Later, lore recall "database" will find it.
With alternatives:
lore capture "Use REST over GraphQL" \
--rationale "Simpler caching, team unfamiliar with GraphQL" \
--alternatives "GraphQL (rejected: learning curve), gRPC (rejected: browser support)"Recording rejected alternatives prevents revisiting settled decisions.
You've learned something reusable -- a technique, a gotcha, a best practice. Add --solution to route to patterns.
lore capture "Retry with exponential backoff" \
--context "Calling external APIs that rate-limit" \
--solution "Base delay 100ms, multiply by 2 each retry, max 5 retries"Patterns surface during future resume calls when the context matches.
Anti-patterns work too:
lore capture "Don't catch generic exceptions" \
--context "Error handling in Python" \
--solution "Catch specific exception types; generic catches hide bugs" \
--category anti-patternSomething went wrong. Record it so recurring failures surface patterns.
lore fail ToolError "Permission denied writing to /etc/hosts"Error types: Timeout, NonZeroExit, UserDeny, ToolError, LogicError
When the same error type recurs three times, lore triggers surfaces it -- the Rule of Three. Recurring failures become patterns worth solving.
recall is the universal read verb. Bare recall searches everything; flags narrow scope.
# Search across all components
lore recall "database"
# Project context (registry + decisions + patterns)
lore recall --project myproject
# Pattern suggestions for a situation
lore recall --patterns "error handling"
# Filtered failure reports
lore recall --failures --type Timeout
# Recurring failure analysis (Rule of Three)
lore recall --triggers
# Topic briefing
lore recall --brief "authentication"Shortcuts like lore search, lore context, and lore triggers still work -- recall unifies them under one verb.
As decisions and patterns accumulate, related records cluster around unnamed themes. Concepts name those themes and become hub nodes in the graph.
# Detect candidate clusters (JSON with names, members, cohesion)
lore concepts propose
# Promote a coherent cluster to a named concept
lore concepts promote "append-only-storage" --members dec-abc123,dec-def456,pat-789abc
# List concepts with member counts
lore concepts listpropose clusters decisions, patterns, and promoted observations by word
similarity, skipping records that already belong to a concept. Review each
candidate and promote only coherent clusters -- concepts need curation.
promote writes the concept to patterns/data/concepts.yaml, creates a
concept node with part_of edges from each member, and indexes it so
lore recall finds it alongside decisions and patterns.
Before ending, capture handoff notes for the next session:
lore handoff "Implemented user auth, need to add OAuth integration next. Blocked on API credentials from infra team."Or capture structured handoff:
lore transfer handoff "Auth 80% complete" \
--next "Add OAuth integration" \
--next "Write auth tests" \
--blocker "Waiting on API credentials" \
--question "Should we support SAML?"The handoff becomes the starting context for whoever resumes next.
Next session, run resume again:
lore resumeYou'll see:
- The parent session's summary and accomplishments
- Inherited handoff notes (next steps, blockers, questions)
- Relevant patterns matched to the context
The cycle continues. Context compounds instead of evaporating.
┌─────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ resume │ ◄─── Load context from parent │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ work │ ◄─── Your actual task │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ capture │ ◄─── Record knowledge (flags) │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ handoff │ ◄─── Context for next session │
│ └────┬─────┘ │
│ │ │
│ └─────────────────────────────────────────┘
Every session follows this pattern. The specific work varies; the lifecycle stays constant.
- Full command reference: Run
lore helpor see README.md - Architecture overview: See SYSTEM.md for how components connect
- MCP integration: See README.md MCP section for AI agent setup
- Advanced search: Try
--graph-depth 2to follow knowledge graph relationships