Portunus — Structured Memory for AI Agents

PORTUNUS

Structured
Memory for
Autonomous Agents

Built for
Autonomous Work

Graph-Aware Context

Entity graphs power smart retrieval. Planning, incident, handoff — each context profile surfaces exactly what your agent needs.

Session Lifecycle

Wake, checkpoint, sleep. Structured session management ensures nothing is lost between runs. Resume from any point.

Task Primitives

Built-in task tracking, backlogs, projects, and kanban boards. Your agent manages work, not just memory.

Obsidian Integration

Canvas dashboards, graph themes, and bidirectional kanban sync. Visualize your vault directly in Obsidian.

Observation Pipeline

Raw transcripts become scored observations, automatically routed into structured memory. Importance-weighted, type-tagged.

Replay Engine

Ingest transcripts from Claude, ChatGPT, OpenCode, and OpenClaw. Every past conversation becomes searchable memory.

Docs

Everything you need — from install to advanced integrations.

# Clone the repository
git clone https://github.com/portunus-code/portunus.git
cd portunus

# Initialize a new vault
portunus init ~/memory --name my-brain

# Bootstrap Obsidian integration
portunus setup --theme neural --canvas

# Start a session
portunus wake

# Store a decision
portunus remember decision "Use PostgreSQL" --content "Chosen for JSONB and reliability"

# Search your vault
portunus search "postgresql"
portunus vsearch "what did we decide about storage"

# Checkpoint during heavy work
portunus checkpoint --working-on "auth rollout" --focus "token refresh"

# End session
portunus sleep "finished auth plan" --next "implement migration"

Requires Node.js 18+. See GitHub for full setup instructions.

Core

init Create or initialize a vault
setup Bootstrap Obsidian config
store Store a raw memory entry
remember Store a typed memory
search Full-text search
vsearch Vector / semantic search
list List vault entries
get Retrieve a specific entry
stats Vault statistics

Context & Memory

context Retrieve relevant context
inject Dynamic prompt injection
observe Run observation pipeline
reflect Generate weekly reflection
graph Explore entity graph
entities List tracked entities
link Create entity links
embed Generate embeddings

Session Management

wake Start a new session
sleep End session with summary
checkpoint Save progress mid-session
recover Recover interrupted session
handoff Transition between agents
status Current session status
recap Session recap

Work Management

task add Create a task
task list List tasks
backlog Manage backlog
blocked Show blocked items
project Manage projects
kanban sync Sync kanban board
canvas Generate dashboard

Vault Structure

vault/
├── .portunus/           # Internal state & config
├── decisions/           # Key architectural choices
├── lessons/             # Insights & learnings
├── people/              # Contact & relationship data
├── projects/            # Active project tracking
├── handoffs/            # Session transition notes
├── inbox/               # Quick captures
└── templates/           # Document templates

Ledger Architecture

ledger/
├── raw/<source>/                       # Raw transcript chunks
├── observations/YYYY/MM/DD.md          # Scored daily observations
├── reflections/YYYY-WNN.md             # Weekly reflections
└── archive/observations/YYYY/MM/DD.md  # Archived observations

Observation Format

# Each observation is scored for confidence (c) and importance (i)
- [decision|c=0.9|i=0.8] Use PostgreSQL for primary datastore
- [lesson|c=0.7|i=0.6] Batch inserts outperform individual writes by 12x
- [fact|c=1.0|i=0.4] API rate limit is 1000 req/min

# Types: decision, preference, fact, commitment,
#        milestone, lesson, relationship, project

Session Workflow

# 1. Start session — loads vault context
portunus wake

# 2. Checkpoint progress at any time
portunus checkpoint --working-on "feature X" --focus "edge cases"

# 3. Retrieve context before complex decisions
portunus context "authentication"
portunus inject "summarize what we know about auth tokens"

# 4. End session — summarize and plan next steps
portunus sleep "completed auth module" --next "write integration tests"

# Recover from interrupted session
portunus recover

# Hand off to another agent
portunus handoff --to agent-02 --context "continue from auth"

Context Profiles

Profile	Purpose	Use Case
default	Balanced retrieval	General tasks and queries
planning	Broader strategic context	Architecture decisions, roadmap
incident	Recent events and blockers	Debugging, firefighting
handoff	Session transition context	Agent-to-agent continuity
auto	Hook-selected profile	Automatic based on current task

Obsidian

Graph themes (neural, minimal), canvas dashboards, Bases views for tasks, bidirectional kanban sync. Run portunus setup --theme neural --canvas to bootstrap.

OpenClaw

First-class hook pack. Install with openclaw hooks install portunus then openclaw hooks enable portunus. Auto session lifecycle and context injection.

Tailscale + WebDAV

Serve vault over Tailscale for mobile sync. WebDAV at /webdav for Obsidian mobile. Run portunus tailscale-serve --vault ~/memory.

Replay Sources

# Ingest transcripts from multiple platforms
portunus replay --source claude      # Anthropic Claude
portunus replay --source chatgpt    # OpenAI ChatGPT
portunus replay --source opencode   # OpenCode sessions
portunus replay --source openclaw   # OpenClaw transcripts

Built forAutonomous Work