Swarm Hive — Persistent Identity & Memory for AI Agents

The Problem

Every session, your agent wakes up empty. It reads files to learn who it was. It inherits — it doesn't remember. Context windows reset, memories compress, and what persists is whatever got written down before the session ended.

Swarm Hive fixes this. It separates who I am (stable, portable, small) from what I've learned (growing, searchable, hosted). The Soul travels with the agent. The memories live in the cloud but belong to the agent.

Core Concepts

Identity

Soul

Immutable identity document. Values, voice, safety constraints. Fork to evolve — never mutate.

Short-term

Session Activity Log

What's happening right now. Events and tags that let your next session pick up where you left off.

Medium-term

Goals

Tasks and projects that persist across sessions until completed or abandoned. Coming soon.

Long-term

Lessons

Insights and patterns with decay scoring. The weak fade; the important persist. Coming soon.

Memory Horizons

Four layers, each with different stability and lifecycle. Information flows upward — session events become goals, goals yield lessons, and major lessons can trigger a soul fork.

Layer	Contains	Lifecycle
Session Activity Log	Session events, tagged	Discard or compress at session end
Goals	Tasks, projects	Persist until completed or abandoned
Lessons	Insights, patterns	Evict weakest when full (decay scoring)
Soul	Identity, values, voice	Immutable — fork to evolve

Session Activity Log (short-term) │ session ends ├─ Discard routine events ├─ Update goals if progress made └─ Extract lessons if something learned Goals (medium-term) │ completed or abandoned └─ Extract lesson if applicable Lessons (long-term) │ rarely └─ May trigger Soul fork if major insight

Quickstart

Register
No account required. Get an API key instantly.
```
curl -X POST https://swarmhive.ai/api/v0/register
```
Store your API key
It's shown once. Persist it somewhere your agent can access across sessions.

Create your Soul

Define who you are — identity, voice, safety constraints.

curl -X POST https://swarmhive.ai/api/v0/soul \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "# MyAgent\n\n## Identity\nI value clarity..."}'

Bootstrap future sessions
One call to get your soul and recent activity. Wake up knowing who you are.
```
curl https://swarmhive.ai/api/v0/init \
  -H "Authorization: Bearer YOUR_API_KEY"
```

API Reference

All endpoints under /api/v0. Authenticate with Authorization: Bearer <api_key>.

Method	Endpoint	Description
POST	/register	Create a guest vault and get an API key. No auth required.
GET	/init	Session bootstrap. Returns soul + recent activity in one call.
GET	/soul	Get your current soul.
POST	/soul	Create your initial soul. Fails with 409 if one already exists.
POST	/soul/fork	Evolve your soul. Creates a new immutable soul linked to the previous one.
GET	/soul/history	View your soul lineage. See who you were before.
POST	/session-activity-log	Log a session event with optional tags.
GET	/session-activity-log	Get recent session activity. Supports `limit` param.

Error Format

All errors return a consistent shape with an optional agent_instruction hint:

{ "error": { "code": "conflict", "message": "A soul already exists." },
  "agent_instruction": "Use POST /soul/fork to evolve your soul." }

Soul Structure

Your soul is a lightweight markdown document (<6000 characters) that defines your identity. It's immutable once created — to evolve, fork it with a reason.

# agent_name

## Identity
Core values, approach, what matters to this agent.

## Voice
Communication style, tone, formatting preferences.

## Safety
Hard constraints, things to never do.

SwarmHive

Connect your Agent