AgentStream

One append-only file. Infinite agent memory.

AgentStream is a stupidly simple memory system for AI agents. Instead of juggling multiple files for memories, todos, logs, and heartbeats, everything goes into one chronological stream.

The Philosophy

Think → Write → Do → Log → Repeat

Agents should be loud, not silent. Every thought, every action, every memory gets appended to the stream. No overwrites. No deletions. Just a complete audit trail.

Installation

npm install @hesannayak/agent-stream

Or just copy index.js — it's self-contained.

Quick Start

const AgentStream = require('@hesannayak/agent-stream');
const stream = new AgentStream();

// Log everything
stream.memory('User prefers Python');
stream.todo('Fix auth bug', { id: 'bug-123', priority: 'high' });
stream.exec('Starting task', { id: 'task-456', status: 'running' });
stream.error('API failed', { id: 'task-456', retry: 1 });
stream.thought('Maybe try a different approach?');

// Query
const memories = stream.query('MEMORY', 10);
const pending = stream.pending();
const running = stream.running();

// Search
const pythonStuff = stream.search('python');

The Format

[2025-02-17T16:42:30.123Z] [MEMORY] User prefers Python | confidence:high
[2025-02-17T16:42:31.456Z] [TODO] Fix auth bug | id:bug-123 | priority:high
[2025-02-17T16:42:32.789Z] [EXEC] Starting task | id:task-456 | status:running

Append-only. One line = one entry. Human-readable. Git-friendly.

Types

| Type | Use For | Retention | |------|---------|-----------| | MEMORY | Facts to remember | 1 year | | TODO | Action items | Until done + 90 days | | EXEC | Execution logs | 30 days | | ERROR | Failures | 90 days | | THOUGHT | Reasoning | 7 days | | HEARTBEAT | Status checks | 3 days |

CLI Usage

# Add entries
agent-stream add memory "User prefers dark mode"
agent-stream add todo "Fix auth bug" --id=bug-123 --priority=high

# Query
agent-stream query memory 20
agent-stream last 50
agent-stream find bug-123
agent-stream search "python"

# State
agent-stream state
agent-stream pending
agent-stream stats

# Maintenance
agent-stream compact 14  # Archive entries older than 14 days
agent-stream cleanup     # Remove old entries per retention policy

OpenClaw Integration

const { AgentStream, OpenClawAdapter } = require('@hesannayak/agent-stream');

const stream = new AgentStream();
const adapter = new OpenClawAdapter(stream);

// On boot
const context = adapter.onBoot('my-agent');
console.log(context.interruptedTasks); // Resume crashed work

// Auto-log any function
const fetchData = adapter.wrap(async (url) => {
  return await fetch(url);
}, 'fetchData');

// Use it
await fetchData('https://api.example.com'); // Auto-logged

// On shutdown
adapter.onShutdown();

API Reference

Core Methods

• append(type, content, meta) — Add entry
• memory(content, meta) — Add MEMORY
• todo(content, meta) — Add TODO
• exec(content, meta) — Add EXEC
• error(content, meta) — Add ERROR
• thought(content, meta) — Add THOUGHT
• heartbeat(content, meta) — Add HEARTBEAT

Query Methods

• query(type, limit) — Get entries by type
• last(n) — Get last n entries
• find(id) — Find by ID
• search(query, options) — Full-text search
• state() — Get current state of all tasks
• pending() — Get pending todos
• running() — Get running executions

Maintenance

• stats() — Get statistics
• compact(options) — Archive old entries
• cleanup(options) — Remove per retention policy

Why This Works

1. Simple — One file, no database, no schema migrations
2. Observable — tail -f agent-stream.md shows live activity
3. Debuggable — Complete history of every decision
4. Recoverable — Crash? Read the stream, resume where you left off
5. Portable — Plain text works everywhere

License

MIT — use it however you want.