Skip to content

Antahkarana

Antahkarana is the Vedic-inspired cognitive layer that sits above the core runtime in SecondBrain. It is an engineering responsibility map for local-first agents, not a claim that a product runtime is a canonical Vedic system.

Purpose

  • add structured attention, identity, goals, judgment, guardrails, memory, and witness-style audit to turns
  • make chat and agent flows more context-aware before tool execution
  • keep the system local-first and deterministic even when optional LLM enrichment is unavailable
  • preserve a clear boundary between traditional Antahkaran faculties and modern runtime extensions

Runtime Position

The practical stack is:

Antahkarana -> Kernel -> Providers / Tools / Local State

The kernel remains the execution substrate. Antahkarana shapes how the system attends, evaluates, and frames work before or around those execution steps.

Current Mental Model

Treat the current implementation as twelve runtime responsibilities plus a functional-state sidecar used to detect pressure or degraded reasoning conditions.

The traditional source anchor is intentionally smaller than the implementation: Manas, Buddhi, Chitta, and Ahamkara are the core inner-faculty inspiration. The remaining names are engineering metaphors or runtime extensions. In particular, the code's AtmanWitness should be read as Witness/Sakshi audit reflection, not as a claim that the machine has Atma.

Named layers in the loop:

  1. Prana
  2. Indriya
  3. Dharana/Dhyana
  4. Manas
  5. Ahamkara
  6. Sankalpa
  7. Buddhi
  8. Viveka
  9. Sabha
  10. Karma
  11. Chitta
  12. Witness/Sakshi

The functional-state monitor lives alongside that loop and feeds pressure or recovery signals into runtime behavior when needed.

SDK Coverage

The public SDK exposes the full loop as read-only local and HTTP integration surfaces:

  • SecondBrain.process_cognitive(...) runs one query through the loop.
  • SecondBrain.cognitive_health() and SecondBrain.cognitive_snapshot(...) inspect stack health and recent traces.
  • SecondBrain.cognitive_layers(), SecondBrain.cognitive_layer_state(...), and SecondBrain.cognitive_stack_state(...) inspect all registered and configured layers.
  • SecondBrain.cognitive_goals(), SecondBrain.cognitive_karma(), SecondBrain.cognitive_chitta(), SecondBrain.cognitive_identity(), and SecondBrain.cognitive_functional_state() expose high-value Sankalpa, Karma, Chitta, Ahamkara, and Bhava summaries without mutating them.

Use this SDK facade for builder integrations. Import from brain.antahkarana directly only when working on the runtime itself.

CLI Surface

sb antahkarana status
sb antahkarana process "What should I focus on today?"
sb antahkarana focus
sb antahkarana salience "urgent production issue"
sb antahkarana chitta
sb antahkarana goals
sb antahkarana karma
sb antahkarana self
sb antahkarana dhyana
sb antahkarana trace <trace_id>

Use sb antahkarana --help and subcommand help for the current live flags.

Relationship To Chat

sb chat uses Antahkarana by default:

sb chat
sb chat --no-antahkarana

That means interactive turns can go through the cognitive loop before the main model/tool turn. Disable it when you need a plainer debugging surface or when comparing behavior directly.

Implementation Pointers

  • brain/antahkarana/README.md
  • brain/antahkarana/loop.py
  • brain/antahkarana/stack.py
  • brain/cli/antahkarana_cmd.py