pi-learn

name	pi-learn
description	Open-source memory infrastructure for pi agents. Provides peer representations, reasoning, context assembly, dreaming, and hybrid memory (global + project-scoped) capabilities. Use when tracking user preferences, maintaining context across sessions, building peer mental models, or enabling persistent agent memory.
risk	safe
source	0xkobold/pi-learn
date_added	2026-03-16

Pi-Learn

Open-source memory infrastructure for pi agents, inspired by Honcho. Enables stateful AI agents with persistent memory, peer understanding, and contextual reasoning.

When to Use

Use pi-learn when:

• You need the agent to remember information across sessions
• Tracking user preferences, interests, and goals
• Building a mental model of the user (peer representation)
• Maintaining project-specific context alongside user profiles
• Enabling creative/dream synthesis for deeper insights
• Cross-project memory sharing vs. project-isolated memory
• Automatic data retention/pruning policies

Core Concepts

Peer Representation

The agent builds mental models of users through:

• Conclusions: Insights extracted from conversations (deductive, inductive, abductive)
• Peer Cards: Biographical data (name, occupation, interests, traits, goals)
• Summaries: Periodic conversation summaries
• Observations: Raw messages stored before reasoning

Hybrid Memory Architecture

Two-tier memory system:

Scope	Storage	Content	Access
Global (user)	__global__ workspace	Traits, interests, goals	All projects
Project (local)	Project workspace	Code patterns, decisions	Current project only

Dreaming

Background reasoning that synthesizes deeper insights. Unlike real-time reasoning, dreaming:

• Runs on a schedule
• Looks at broader patterns
• Generates creative hypotheses

Tools (28 total)

Core Memory Tools

Tool	Description
learn_add_message	Store a message for future reasoning
learn_add_messages_batch	Bulk insert multiple messages
learn_add_observation	Store raw observation before reasoning
learn_get_context	Retrieve assembled peer context (blended)
learn_query	Semantic search through memories

Reasoning Tools

Tool	Description
learn_reason_now	Trigger immediate reasoning
learn_trigger_dream	Manually trigger dream cycle

Peer Card Tools

Tool	Description
learn_get_peer_card	Get biographical info card
learn_update_peer_card	Manually update peer card

Session Tools

Tool	Description
learn_list_peers	List all peers in workspace
learn_list_sessions	List all sessions
learn_get_session	Get specific session with messages
learn_search_sessions	Search sessions by keyword
learn_tag_session	Add/remove session tags
learn_get_sessions_by_tag	Get sessions by tag
learn_list_tags	List all unique tags

Statistics & Insights

Tool	Description
learn_get_stats	Get memory statistics
learn_get_insights	Comprehensive learning patterns
learn_get_summaries	Get peer summaries
learn_get_dream_status	Dream system status

Data Management

Tool	Description
learn_prune	Trigger retention pruning
learn_export	Export all memory as JSON
learn_import	Import from JSON backup

Cross-Peer Tools

Tool	Description
learn_observe_peer	Record observation about another peer
learn_get_perspective	Get perspective from one peer on another

Scope-Specific Context

Tool	Description
learn_get_global_context	Get cross-project context only
learn_get_project_context	Get project-specific context only

Usage Examples

Basic: Store and Retrieve Context

// Add user message to memory
learn_add_message({
  content: "I'm really interested in functional programming and TypeScript",
  role: "user"
});

// Later, retrieve assembled context
const context = learn_get_context({});
// Returns: blended global + project context with interests, traits, conclusions

Intermediate: Query Specific Memories

// Search for conclusions about a topic
const results = learn_query({
  query: "TypeScript preferences",
  topK: 5,
  minSimilarity: 0.5
});

// Get comprehensive stats
const stats = learn_get_stats({});
// Returns: conclusionCount, summaryCount, topInterests, topTraits, etc.

Advanced: Trigger Dreaming

// Manually trigger dream cycle
learn_trigger_dream({
  scope: "project"  // or "user" for global
});

// Check dream status
const status = learn_get_dream_status({});
// Returns: lastDreamedAt, dreamCount, nextDreamMs, etc.

Cross-Peer: Observe Other Agents

// Record observation about another peer
learn_observe_peer({
  aboutPeerId: "coding-agent",
  content: "Responds quickly and prefers TypeScript"
});

// Get perspective from user's view
const perspective = learn_get_perspective({
  observerPeerId: "user",
  targetPeerId: "coding-agent"
});

Configuration

{
  "learn": {
    "workspaceId": "default",
    "reasoningEnabled": true,
    "reasoningModel": "qwen3.5:latest",
    "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,
      "pruneOnStartup": true,
      "pruneIntervalHours": 24
    }
  },
  "ollama": {
    "apiKey": "your-api-key"
  }
}

CLI Commands

Command	Description
/learn status	Show memory status
/learn context	Show assembled context
/learn config	Show configuration
/learn dream	Trigger dream cycle
/learn prune	Prune old data
/learn search <query>	Search sessions
/learn sessions	List sessions

Conclusion Types

Type	Confidence	Description
Deductive	80-100%	Logical certainty from explicit premises
Inductive	60-80%	Pattern observed across messages
Abductive	40-60%	Best explanation for behavior

Architecture

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

Data Storage

SQLite database at ~/.pi/memory/pi-learn.db:

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

-- Indexes
idx_conclusions_peer, idx_conclusions_created
idx_summaries_peer, idx_messages_session

Ollama Requirements

Requires Ollama running locally with:

• Embeddings: nomic-embed-text-v2-moe:latest
• Reasoning: Any Ollama chat model

ollama pull nomic-embed-text-v2-moe:latest
ollama pull qwen3.5:latest

See Also

• Hybrid Memory Architecture
• pi-ollama - Ollama integration
• Honcho - Inspiration for this project