npm package: @hesannayak/agent-stream
Description: Append-only memory stream for AI agents - one file, infinite memory
Author: OpenClaw Community
Latest version: 1.0.1

# 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

```bash
npm install @hesannayak/agent-stream
```

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

## Quick Start

```javascript
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

```bash
# 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

```javascript
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.