cogito

LLM-powered reasoning chains with semantic memory for Go.

Build autonomous systems that reason, remember, and adapt.

Reasoning That Accumulates

A Thought is a reasoning context. Primitives read it, reason via LLM, and contribute Notes back. Each step sees what came before.

thought, _ := cogito.New(ctx, memory, "should we approve this refund?")
thought.SetContent(ctx, "request", customerEmail, "input")

// Pipeline: each primitive builds on accumulated context
pipeline := cogito.Sequence("refund-decision",
    cogito.NewAnalyze[RefundRequest]("parse", "extract order ID, amount, and reason"),
    cogito.NewSeek("history", "this customer's previous refund requests"),
    cogito.NewDecide("approve", "does this meet our refund policy?").
        WithIntrospection(),
)

result, _ := pipeline.Process(ctx, thought)

// Every step left a Note — an auditable chain of reasoning
for _, note := range result.AllNotes() {
    fmt.Printf("[%s] %s: %s\n", note.Source, note.Key, note.Content)
}
// [input] request: "I'd like a refund for order #12345..."
// [analyze] parse: {"order_id": "12345", "amount": 49.99, "reason": "arrived damaged"}
// [seek] history: "No previous refund requests found for this customer"
// [decide] approve: "yes"
// [introspect] approve: "Approved: first-time request, clear damage claim, within policy window"

Introspection adds a semantic summary explaining why — context for subsequent steps or human review. Notes persist with vector embeddings, enabling semantic search across all stored reasoning.

Install

go get github.com/zoobzio/cogito

Requires Go 1.21+.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/zoobzio/cogito"
)

type TicketData struct {
    CustomerName string   `json:"customer_name"`
    Issue        string   `json:"issue"`
    Urgency      []string `json:"urgency_indicators"`
}

func main() {
    ctx := context.Background()

    // Configure providers
    cogito.SetProvider(myLLMProvider)
    cogito.SetEmbedder(cogito.NewOpenAIEmbedder(apiKey))

    // Connect to memory (implement cogito.Memory interface)
    memory := NewMyMemory()

    // Build a reasoning pipeline
    pipeline := cogito.Sequence("ticket-triage",
        cogito.NewAnalyze[TicketData]("parse",
            "extract customer name, issue description, and urgency indicators"),
        cogito.NewSeek("history", "similar support issues and resolutions").
            WithLimit(5),
        cogito.NewCategorize("category", "what type of support issue is this?",
            []string{"billing", "technical", "account", "feature_request"}),
        cogito.NewAssess("urgency",
            "how urgent is this ticket based on tone and content?"),
        cogito.NewDecide("escalate",
            "should this ticket be escalated to a senior agent?").
            WithIntrospection(),
    )

    // Create a thought with initial context
    thought, _ := cogito.New(ctx, memory, "triage support ticket")
    thought.SetContent(ctx, "ticket", incomingTicket, "input")

    // Execute the pipeline
    result, err := pipeline.Process(ctx, thought)
    if err != nil {
        log.Fatal(err)
    }

    // Results are Notes
    category, _ := result.GetContent("category")
    escalate, _ := result.GetContent("escalate")
    fmt.Printf("Category: %s, Escalate: %s\n", category, escalate)
}

Capabilities

Feature	Description	Docs
Reasoning Primitives	Decide, Analyze, Categorize, Assess, Prioritize	Primitives
Semantic Control Flow	Sift (LLM gate) and Discern (LLM router)	Control Flow
Memory & Reflection	Recall, Reflect, Checkpoint, Seek, Survey	Memory
Session Management	Compress and Truncate for token control	Sessions
Synthesis	Amplify (iterative refinement), Converge (parallel synthesis)	Synthesis
Two-Phase Reasoning	Deterministic decisions with optional creative introspection	Introspection

Why cogito?

• Composable reasoning — Chain primitives into pipelines via pipz
• Semantic memory — Notes persist with vector embeddings for similarity search
• Context accumulation — Each step builds on previous reasoning
• Two-phase reasoning — Deterministic decisions with optional creative introspection
• Observable — Emits capitan signals throughout execution
• Extensible — Implement pipz.Chainable[*Thought] for custom primitives

Semantic Control Flow

Traditional pipelines route on data. Cogito routes on meaning.

// Sift: LLM decides whether to execute
urgent := cogito.NewSift("urgent-only",
    "is this request time-sensitive?",
    expeditedHandler,
)

// Discern: LLM classifies and routes
router := cogito.NewDiscern("route", "how should we handle this?",
    map[string]pipz.Chainable[*cogito.Thought]{
        "approve": approvalFlow,
        "review":  manualReviewFlow,
        "decline": declineFlow,
    },
)

Control flow adapts to domain changes without code changes — the LLM interprets intent.

Integrate with flume for declarative, hot-reloadable pipeline definitions.

Documentation

• Overview — Design philosophy and architecture

Learn

• Quickstart — Build your first reasoning pipeline
• Primitives — Decide, Analyze, Categorize, and more
• Introspection — Two-phase reasoning
• Architecture — Thought-Note-Memory model

Guides

• Control Flow — Sift and Discern for semantic routing
• Memory — Persistence and semantic search
• Sessions — Token management with Compress and Truncate
• Synthesis — Amplify and Converge patterns
• Custom Primitives — Implementing Chainable[*Thought]
• Testing — Testing reasoning pipelines

Cookbook

• Support Triage — Ticket classification and routing
• Document Analysis — Extract and reason over documents
• Decision Workflows — Multi-step approval flows

Reference

• API — Complete function documentation
• Primitives — All primitives with signatures
• Types — Thought, Note, Memory, Provider

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.