@0xkobold/pi-learn

Open-source memory infrastructure for pi agents, inspired by Honcho.

Part of the 0xKobold ecosystem.

Installation

Bundled (recommended)

pi install npm:@0xkobold/pi-kobold
# pi-learn loaded as sub-extension automatically

Standalone

pi install npm:@0xkobold/pi-learn

# Or in pi-config.ts
{
  extensions: [
    'npm:@0xkobold/pi-learn'
  ]
}

# Or temporary (testing)
pi -e npm:@0xkobold/pi-learn

Features

• Peer Representations: Build rich mental models of users through reasoning
• LLM-Based Reasoning: Uses Ollama for embeddings and reasoning (local or cloud)
• Context Assembly: Retrieves relevant context for agent prompts
• Vector Search: Semantic similarity search using embeddings with keyword fallback
• Dreaming: Background/creative reasoning synthesis
• Observation Bridge: Unprocessed observations automatically flow into reasoning pipeline
• Session Summarization: Auto-generates short and long summaries at message thresholds
• Retention Policies: Automatic data pruning

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Pi-Learn                             │
├─────────────────────────────────────────────────────────────┤
│  Session Events    │  SQLiteStore   │  Reasoning Engine   │
│  ────────────────  │  ─────────────  │  ────────────────  │
│  • session_start   │  • Workspaces   │  • Message batch    │
│  • before_agent    │  • Peers        │  • Conclusions      │
│  • message_end     │  • Sessions     │  • Observations     │
│  • turn_end        │  • Messages     │  • Peer cards       │
│                    │  • Conclusions  │  • Summaries        │
│                    │  • Observations │  • Dreaming        │
├─────────────────────────────────────────────────────────────┤
│                    Ollama Integration                       │
│  ┌─────────────────┐        ┌─────────────────────────┐  │
│  │ Embeddings       │        │ Reasoning Model          │  │
│  │ nomic-embed-     │        │ (configurable)          │  │
│  │ text-v2-moe      │        │                          │  │
│  └─────────────────┘        └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Data Model

Inspired by Honcho's hierarchical structure:

1. Workspace: Top-level container (isolated namespaces)
2. Peer: User, agent, or entity being observed
3. Session: Interaction thread between peers
4. Message: Individual conversation entries
5. Observation: Raw observations stored before reasoning
6. Conclusion: Synthesized insights from reasoning
7. Representation: Aggregated peer knowledge

Reasoning Pipeline

Messages flow through a full pipeline:

1. Add message → stored with processed=false
2. learn_reason_now → fetches unprocessed observations, runs LLM reasoning, saves conclusions with embeddings, marks observations as processed
3. autoSummarize → generates short summaries every 20 messages, long summaries every 60 messages
4. searchSimilar → uses vector similarity (cosine similarity on embeddings) with keyword fallback

Conclusion Types

• Deductive: Certain conclusions from explicit premises (90% confidence)
• Inductive: Patterns observed across messages (70% confidence)
• Abductive: Simplest explanations for behavior (50% confidence)

Peer Cards

Biographical cache:

• Name, occupation
• Interests, traits, goals
• Updated through reasoning or manually

Dreaming

Dreaming is background reasoning that synthesizes deeper insights:

• Runs on a schedule (configurable interval)
• Looks at broader patterns across sessions
• Generates creative hypotheses about the peer
• Can update peer cards with insights

Retention Policies

Automatic data pruning:

• Summaries: Default 30 days retention
• Conclusions: Default 90 days retention
• Messages: Forever by default (configurable)

Commands

| Command | Description | |---------|-------------| | /learn status | Show memory status | | /learn context | Show assembled context | | /learn config | Show configuration | | /learn enable | Enable reasoning | | /learn disable | Disable reasoning | | /learn dream | Trigger dream cycle | | /learn prune | Prune old data |

Tools (14 total)

| Tool | Description | |------|-------------| | learn_add_message | Add a message to memory | | learn_add_observation | Store raw observation for later reasoning | | learn_add_messages_batch | Batch add multiple messages | | learn_get_context | Retrieve assembled peer context | | learn_query | Search memory with embeddings | | learn_reason_now | Trigger immediate reasoning on unprocessed observations | | learn_trigger_dream | Manually trigger dreaming | | learn_get_peer_card | Get biographical info card | | learn_update_peer_card | Update peer card manually | | learn_list_peers | List all peers in workspace | | learn_get_stats | Get memory statistics | | learn_get_summaries | Get peer summaries | | learn_prune | Trigger retention pruning | | learn_search_sessions | Search sessions by keyword | | learn_get_session | Get specific session with messages | | learn_list_sessions | List all sessions | | learn_tag_session | Tag sessions for categorization |

Configuration

{
  "learn": {
    "workspaceId": "default",
    "reasoningEnabled": true,
    "reasoningModel": "kimi-k2.5:cloud",
    "embeddingModel": "nomic-embed-text-v2-moe:latest",
    "tokenBatchSize": 1000,
    "dream": {
      "enabled": true,
      "intervalMs": 3600000,
      "minMessagesSinceLastDream": 5,
      "batchSize": 50
    },
    "retention": {
      "summaryRetentionDays": 30,
      "conclusionRetentionDays": 90,
      "retentionDays": 0
    }
  },
  "ollama": {
    "apiKey": "your-api-key"
  }
}

Environment variables:

• LEARN_REASONING_MODEL - Override reasoning model
• LEARN_EMBEDDING_MODEL - Override embedding model
• LEARN_TOKEN_BATCH_SIZE - Override token batch size
• OLLAMA_API_KEY - Override Ollama API key

API Functions

Library functions are importable for programmatic use:

// Core modules
import { SQLiteStore } from "@0xkobold/pi-learn/core/store";
import { ReasoningEngine, type ReasonedConclusion } from "@0xkobold/pi-learn/core/reasoning";
import { ContextAssembler } from "@0xkobold/pi-learn/core/context";

// Shared types and utilities
import { cosineSimilarity, GLOBAL_WORKSPACE_ID } from "@0xkobold/pi-learn/shared";

// CLI renderers
import { renderStats, renderPeerCard } from "@0xkobold/pi-learn/renderers";

// Use vector search
const store = new SQLiteStore(dbPath);
const results = await store.searchSimilar(workspaceId, peerId, "query text", 10);

// Manual reasoning
const reasoningEngine = new ReasoningEngine(ollama, model);
const conclusions = await reasoningEngine.reasonOnObservations(workspaceId, peerId, observations);

// Auto-summarize at thresholds
const assembler = new ContextAssembler(store, ollama, model);
await assembler.autoSummarize(workspaceId, peerId, reasoningEngine);

Local Storage

Data is stored in SQLite at ~/.pi/memory/pi-learn.db:

-- Tables
workspaces, peers, sessions, messages,
observations, conclusions, summaries, peer_cards

-- Indexes for performance
idx_conclusions_peer, idx_conclusions_created,
idx_summaries_peer, idx_messages_session

Ollama Requirements

Pi-learn requires Ollama running locally or via cloud:

• Embeddings: nomic-embed-text-v2-moe:latest (required for semantic search)
• Reasoning: Any Ollama chat model (default: kimi-k2.5:cloud)

# Pull required models
ollama pull nomic-embed-text-v2-moe:latest

# Pull your preferred reasoning model
ollama pull kimi-k2.5:cloud

Related Packages

• @0xkobold/pi-kobold — Meta-extension that bundles this and other sub-extensions
• @0xkobold/pi-ollama — Ollama integration for pi agents
• @0xkobold/pi-persona — Scope-aware persona management

Local Development

git clone https://github.com/0xKobold/pi-learn
cd pi-learn
npm install
npm run build
pi install ./

Changelog

See CHANGELOG.md for version history.

License

MIT