titan-pi-memory

Persistent evolutionary memory for the Pi coding agent. Titan remembers across sessions — decisions, bugs, architecture, preferences. Conversations become knowledge. Nothing is lost.

pi install npm:titan-pi-memory

---

Install (60 seconds)

What you need

• Pi coding agent installed (npm install -g @earendil-works/pi-coding-agent)
• Python 3.10+ (check with python3 --version)
• An API key for your chosen extraction provider:
  • Gemini — free tier at aistudio.google.com (recommended)
  • OpenAI — platform.openai.com
  • DeepSeek — platform.deepseek.com
  • OpenRouter — openrouter.ai

Step 1: Install the package

pi install npm:titan-pi-memory

Step 2: Set up

Open Pi and type:

/titan-setup

This creates your Titan workspace and installs everything needed.

Step 3: Add your API key

/titan-key

Titan will walk you through picking a provider, selecting a model, and entering your API key. Choose from Gemini, OpenAI, OpenRouter, or DeepSeek. Done.

Step 4: Embedding model (optional)

By default, Titan runs a local embedding model via Ollama for semantic search.

~/.titan/agents/pi/config/embedding_models.yaml

Edit that file to switch to OpenAI embeddings or keep the local default (no setup needed if Ollama is running).

Step 5: Verify it's working

/titan-status

You should see:

Server:     running
Workspace:  ~/.titan/agents/pi
Memories:   {"memory_count": 0}

Step 6: Done

Every conversation from now on gets remembered.

/titan-save I just configured Titan for the first time

Come back tomorrow — Pi will know what you were working on.

---

Features

Agent memory (always on)

Titan listens to your Pi conversations and saves everything automatically. Every decision, bug fix, preference, and architectural choice is captured. Your agent remembers across sessions — no more repeating yourself.

Semantic memory search

Query everything Titan has stored:

/titan-query what database does this project use?

Titan finds the most relevant memories, even when you don't remember the exact words.

Full scene context

Every memory links back to the conversation it came from. When your agent finds a relevant memory, it can pull up the full discussion with a single tool call — so it understands the why behind the fact, not just the fact itself.

Work pattern discovery

As your memory graph grows, something interesting happens. You start seeing patterns in your own work — what you consistently care about, how your thinking evolves, what kinds of problems you keep running into.

Open your graph after a few sessions:

/titan-graph

Users describe it like this:

"Very addictive. Watching it grow and develop. You get to know yourself better using it." — Elina, daily Titan user

The graph shows your memories as clusters of related topics. Look at the connections. You might recognize something.

---

Tools (what Pi can do)

Your Pi agent has these tools available automatically:

Tool	What it does
titan_query_memories	Search across all memories (semantic)
titan_get_scene_context	Get the full conversation for a memory
titan_store_trace_packet	Manually save an important decision
titan_get_recent_memories	Browse recent memories
titan_doctor	Check if everything is healthy

---

Commands (what you can type)

Command	What it does
/titan-graph	Open your knowledge graph in the browser
/titan-setup	Set up your workspace and start the server
/titan-key	Add or change your API key
/titan-query <q>	Search your memories
/titan-recent	Browse recent memories
/titan-status	Check if Titan is running
/titan-save <goal>	Save a manual memory
/titan-start	Start the Titan server
/titan-dashboard	Open a rich terminal memory dashboard
/titan-clusters	List your memory topic clusters
/memory-sync	Import useful memories from local Claude Code/Codex sessions into Titan
/skill:memory-sync	Load the Memory Sync skill directly

---

Configuration

Switch extraction model

Default is Gemini 2.5 Pro. Edit:

~/.titan/agents/pi/config/extraction_models.yaml

Set current: to openai, openrouter, deepseek, or ollama, then add the corresponding API key via /titan-key.

Or use /titan-key directly — it walks you through picking provider, model, and key all at once.

Switch embedding model

Default is Ollama + nomic-embed-text (runs locally, needs Ollama running).

Edit ~/.titan/agents/pi/config/embedding_models.yaml to switch.

---

Development

# Edit the extension
vim tools/pi_extension/index.ts

# Reload in Pi
/reload

# Check for TypeScript errors
npx tsc --noEmit tools/pi_extension/index.ts

---

Links

• npm: npmjs.com/package/titan-pi-memory
• Repository: github.com/kuwosaad/titan-karu
• Pi packages: pi.dev/packages

---

Repository Layout

app/             → Memory engine (save pipeline, retrieval, graph, storage, API)
tools/           → Pi extension (pi_extension/), CLI, benchmarks
entrypoints/     → HTTP server and MCP server
config/          → Model and runtime configuration
assets/          → Brand, logos, design files
docs/            → Contributor docs, plans, benchmarks
experiments/     → Research code (not product runtime)

---

For Developers

How It Works

Agent session
       │
       ▼
┌──────────────┐
│  Spool File   │  The Pi extension writes every chat
│  (.jsonl)     │  event into a spool file
└──────┬───────┘
       │  Auto-ingest picks up new events every 3 seconds
       ▼
┌──────────────┐
│ Event Ledger  │  Permanent, deduplicated log of all events
│ (events.jsonl)│
└──────┬───────┘
       │  Process new events (after last checkpoint)
       ▼
┌──────────────┐
│  Extraction   │  LLM reads the conversation and pulls out atomic facts
│  + Embedding  │  Each fact gets a vector for semantic search
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Memory Store  │  SQLite database with memories + embeddings
│ (SQLite)      │
└──────┬───────┘
       │
       ▼
  Agent asks "what do you remember about X?"
     → Semantic search → Compact brief → Returned to agent

API Reference

Endpoint	Method	What it does
/api/ingest/event	POST	Ingest a single event
/api/ingest/spool	POST	Ingest all events from a session
/api/retrieve	GET	Semantic search with compact brief
/api/memories	GET	Browse stored memories
/graph	GET	Interactive knowledge graph
/api/clusters	GET	List memory topic clusters
/api/clusters/analyze	GET	Cross-cluster analysis
/api/debug/pipeline	GET	Check ingest health

Example search:

curl "http://127.0.0.1:8000/api/retrieve?query=what+database+does+the+project+use"

CLI Commands

If installed via pip, use titan. Otherwise: python3 tools/cli/titan.py

Command	What it does
titan doctor --agent <name>	Verify memory readiness
titan init --agent <name>	Prepare runtime home for an agent
titan mcp --agent <name>	Start MCP server for that agent
titan config show	Show current model config
titan config set-model	Change extraction/embedding models
titan key set <KEY_NAME>	Set an API key
titan graph --agent <name>	Build and open the knowledge graph

Project Structure

titan-karu/
├── app/
│   ├── save_pipeline/      # Save flow: ingest → extract → embed → store
│   │   └── extraction/     # LLM-based memory extraction
│   ├── embedding/          # Vector embedding (Ollama / OpenAI)
│   ├── graph/              # Memory graph builder, clusters, UI
│   ├── retrieval_pipeline/ # Retrieval: router, retriever, brief
│   ├── api/                # FastAPI HTTP endpoints
│   └── storage/            # SQLite-backed memory store
├── config/                 # YAML configuration
├── entrypoints/            # HTTP server, MCP server
├── tools/
│   ├── cli/titan.py        # CLI tool
│   ├── pi_extension/       # Pi extension (TypeScript + Python)
│   └── benchmarks/         # Benchmark harnesses
└── docs/                   # Contributor docs

Running Tests

pytest

Security

• All API keys stored in .env (gitignored)
• Server runs on 127.0.0.1 (localhost only) by default
• All data stays on your machine

---