Knowledge assimilation lifecycle

SecondBrain can now track an idea as it moves from raw intake to reflected understanding to practiced knowledge.

The user-facing model is:

Raw Intake -> Reflected Understanding -> Practiced Wisdom

In Vedic-Upanishadic terms, the commands are:

Stage	Meaning	SecondBrain command
Shravan	Receive knowledge from a source with attention and provenance	sb knowledge shravan add
Manan	Reflect, question, connect, and resolve doubt	sb knowledge manan reflect
Nididhyasan	Convert reflected knowledge into repeated practice	sb knowledge nididhyasan implement

The important product idea is simple: SecondBrain does not treat every note as equally mature. A captured note is not the same as knowledge you have questioned and then used.

When to use this

Use the assimilation lifecycle for ideas that may change how you think or act:

• a principle from a book, scripture, paper, talk, or course
• a design lesson from a project or code review
• a strategic insight from a meeting
• a recurring pattern from your notes
• a rule you want SecondBrain to help you practice
• a claim that should not become durable memory until it has source context

For ordinary one-off capture, continue using:

sb capture note "Remember this"
sb capture file path/to/doc.pdf
sb capture web https://example.com

For material that deserves deliberate assimilation, use:

sb knowledge shravan add "I learned that good AI agents need eval harnesses before production." \
  --source engineering_discussion \
  --title "Agent eval discussion" \
  --authority secondary \
  --trust-score 0.8 \
  --relevance-score 0.9

The lifecycle at a glance

flowchart TD
    A["Shravan: source-aware intake"] --> B["Manan: reflection and synthesis"]
    B --> C["Nididhyasan: practice loop"]
    C --> D["Lived memory"]

Each stage writes a durable local record in the knowledge database. You can inspect status, review gaps, and continue the lifecycle later.

Stage 1: Shravan

Shravan records what was heard or read, where it came from, and why it matters. It is not just a summary.

sb knowledge shravan add "No raw capture should go directly into durable memory." \
  --source design_note \
  --title "Memory lifecycle note" \
  --authority primary \
  --lineage "SecondBrain design principle" \
  --trust-score 0.9 \
  --freshness-score 0.8 \
  --relevance-score 1.0 \
  --why "This changes how memory promotion should work."

The command produces:

1. What was heard/read
2. Source
3. Core teaching
4. What is unclear
5. What needs contemplation
6. Practical application

Input from a file

sb knowledge shravan add --file notes/agent-evals.md \
  --source paper \
  --title "Agent evaluation notes" \
  --authority secondary \
  --trust-score 0.75

Input from an existing capture

If you already captured something through sb capture, start the lifecycle from the capture id:

sb capture note "Good AI agents need eval harnesses before production." --json
sb knowledge shravan add --capture-id cap_abc123 \
  --title "Agent eval discussion" \
  --authority secondary \
  --trust-score 0.8

When a capture id is supplied, SecondBrain reuses the capture source type, source reference, title hint, raw text, and existing trust score where available.

Source fields

Field	Purpose
--source	Source type, such as book, meeting, paper, scripture, video, thought, or engineering_discussion
--title	Human-readable source title
--authority	primary, secondary, opinion, or unknown
--lineage	Where the knowledge came from or how it should be traced
--source-ref	URL, path, citation, meeting id, or other source anchor
--trust-score	Reliability score from 0.0 to 1.0
--freshness-score	Currentness score from 0.0 to 1.0
--relevance-score	How relevant this is to you now, from 0.0 to 1.0
--open-question	Question to carry into reflection; repeatable

JSON output

sb knowledge shravan add "Agents need evals." \
  --source design_note \
  --title "Agent eval principle" \
  --json

The JSON contains:

{
  "record": {
    "stage": "shravan",
    "shravan_id": "shravan_...",
    "source": {
      "type": "design_note",
      "title": "Agent eval principle",
      "authority_level": "unknown",
      "lineage": null,
      "source_ref": null,
      "trust_score": 0.0,
      "freshness_score": 0.5,
      "relevance_score": 0.5
    },
    "initial_summary": "Agents need evals.",
    "open_questions": [
      "What is still unclear or unsupported?",
      "What should change in thinking, design, or execution?",
      "What practice or outcome would validate this knowledge?"
    ]
  },
  "knowledge_maturity": {
    "shravan_score": 0.3,
    "manan_score": 0.0,
    "nididhyasan_score": 0.0,
    "overall_state": "captured_not_yet_reflected",
    "memory_type": "Heard Memory"
  },
  "next_stage": "manan"
}

Stage 2: Manan

Manan reflects on a Shravan intake. It extracts claims, questions, counterpoints, connections, resolved understanding, and principles.

sb knowledge manan reflect shravan_abc123

You can add your own questions, connections, or counterpoints:

sb knowledge manan reflect shravan_abc123 \
  --question "What eval dimensions matter most?" \
  --connect "PULSE harness" \
  --connect "release gates" \
  --counterpoint "Small prototypes may not need a full harness yet."

The command produces:

Core idea:
Why it matters:
Questions:
Contradictions:
Connection to existing memory:
Possible implementation:
Decision/action implication:

JSON output

sb knowledge manan reflect shravan_abc123 --json

The JSON includes:

{
  "record": {
    "stage": "manan",
    "manan_id": "manan_...",
    "linked_shravan_id": "shravan_...",
    "core_claims": [
      "Good AI agents should use eval harnesses before production"
    ],
    "questions": [
      "What is still unclear or unsupported?",
      "What should change in thinking, design, or execution?"
    ],
    "counterpoints": [
      "Not every captured note deserves deep reflection or durable memory."
    ],
    "connections": [
      "source:engineering_discussion",
      "authority:secondary"
    ],
    "principles": [
      "Good AI agents should use eval harnesses before production"
    ]
  },
  "knowledge_maturity": {
    "overall_state": "reflected_not_yet_practiced",
    "memory_type": "Reflected Memory"
  },
  "next_stage": "nididhyasan"
}

Stage 3: Nididhyasan

Nididhyasan turns reflected knowledge into a practice loop. This is the step where knowledge starts becoming lived behavior.

sb knowledge nididhyasan implement manan_abc123 \
  --type checklist \
  --title "Agent release eval checklist" \
  --frequency weekly \
  --success-metric "Every production agent has scenario coverage, golden tests, and observability."

Implementation types:

Type	Use it for
habit	A recurring personal practice
task	A concrete next action
rule	A decision rule or guardrail
checklist	A repeatable verification list
project	A project or larger implementation effort
principle	A personal or system operating principle

The command produces:

1. What should change
2. Type
3. Practice
4. Success metric
5. Review

Example

sb knowledge nididhyasan implement manan_abc123 \
  --type rule \
  --title "No agent workflow ships without eval coverage" \
  --frequency weekly \
  --review-prompt "Which agent workflows moved forward without eval evidence?" \
  --success-metric "New agent workflows include scenario simulation, regression tests, and trace visibility."

Knowledge maturity

SecondBrain assigns a maturity score to each lifecycle item:

Score	Meaning
shravan_score	Was the source captured clearly and reliably?
manan_score	Has it been questioned, connected, and synthesized?
nididhyasan_score	Has it been converted into practice or action?

The resulting memory types are:

Memory type	Meaning
Heard Memory	Captured but not yet reflected
Reflected Memory	Questioned and synthesized, but not yet practiced
Practiced Memory	A practice loop exists
Lived Memory	Practice is strong enough to be treated as durable operating knowledge

View current status:

sb knowledge status
sb knowledge status --json

Typical JSON:

{
  "counts": {
    "shravan": 4,
    "manan": 2,
    "nididhyasan": 1
  },
  "needs_manan": ["shravan_..."],
  "needs_nididhyasan": ["manan_..."],
  "maturity_states": {
    "captured_not_yet_reflected": 2,
    "reflected_not_yet_practiced": 1,
    "practice_started": 1
  }
}

Weekly review

Use weekly review to find captured ideas that have not yet become reflected or practiced:

sb knowledge review --weekly

This shows:

• Shravan records that need Manan
• Manan records that need Nididhyasan
• suggested commands for the next step

JSON mode is useful for scripts:

sb knowledge review --weekly --json

Memory API and MCP access

The same lifecycle is available through the public Memory API and Claude Code MCP server.

Stage	HTTP	MCP tool
Shravan	POST /v1/memory/assimilation/shravan	secondbrain_shravan_add
Manan	POST /v1/memory/assimilation/manan	secondbrain_manan_reflect
Nididhyasan	POST /v1/memory/assimilation/nididhyasan	secondbrain_nididhyasan_implement
Status	GET /v1/memory/assimilation/status	secondbrain_knowledge_status
Review	GET /v1/memory/assimilation/review	secondbrain_knowledge_review

Example HTTP flow:

curl -s -H "Authorization: Bearer ${SB_SERVE_TOKEN}" \
  -H "Content-Type: application/json" \
  http://localhost:8765/v1/memory/assimilation/shravan \
  -d '{
    "content": "Good AI agents need eval harnesses before production.",
    "source_type": "engineering_discussion",
    "source_title": "Agent eval discussion",
    "authority": "secondary",
    "trust_score": 0.8,
    "relevance_score": 0.9
  }'

Each Memory API response includes:

• record: the durable Shravan, Manan, or Nididhyasan object
• knowledge_maturity: scores for captured, reflected, and practiced knowledge
• citations: a provenance envelope for the stage record
• next_stage: the next lifecycle step

For Nididhyasan, set propose_memory to true when you want a governed long-term-memory proposal:

{
  "manan_id": "manan_...",
  "implementation_type": "rule",
  "title": "No agent workflow ships without eval coverage",
  "propose_memory": true
}

That creates a pending memory review item. It does not directly write durable memory.

Recommended workflow

For a single insight:

sb knowledge shravan add "Good AI agents need eval harnesses before production." \
  --source engineering_discussion \
  --title "Agent eval discussion" \
  --authority secondary \
  --trust-score 0.8 \
  --relevance-score 0.9 \
  --json

sb knowledge manan reflect shravan_abc123 \
  --connect "PULSE" \
  --connect "release checklist" \
  --json

sb knowledge nididhyasan implement manan_abc123 \
  --type checklist \
  --title "Agent release eval checklist" \
  --json

For regular use:

1. Capture freely with sb capture ....
2. Promote only meaningful items into Shravan.
3. Review pending Shravan items weekly.
4. Reflect on only the ideas that matter.
5. Convert strong reflections into tasks, habits, rules, checklists, projects, or principles.
6. Treat practiced knowledge as higher trust than raw notes.

Storage and privacy

The lifecycle is local-first. Records are stored in the split knowledge database under the tables:

• knowledge_shravan_records
• knowledge_manan_records
• knowledge_nididhyasan_records

The lifecycle does not call an LLM. The first implementation is deterministic and offline-safe. It records source and practice structure now; later agents can use the same records for richer retrieval, reflection, and memory governance.

Limitations

• The current reflection and implementation builders are deterministic. They produce useful structure, but they are intentionally conservative.
• Creating a Nididhyasan record does not automatically mark a habit or task as completed. It creates the practice loop and maturity record.
• Long-term memory promotion is not automatic. The lifecycle marks whether a record is eligible for durable memory; governance and review flows still decide what becomes durable memory.
• Scores are maturity indicators, not truth scores. Source authority and lived practice still require human judgment.

Related commands

sb capture note "Remember this"
sb capture status
sb knowledge inspect <id_or_query>
sb knowledge status
sb knowledge review --weekly
sb memory review-list
sb memory stats

Related docs:

• Ingest and Context
• Memory
• CLI Reference