agenome 0.1.0

Agent genome hub — sync AI agent identity, memory, and sessions across machines and frameworks

Agenome

Your agent's genome — identity, memory, and sessions that travel with you.

Agenome is a state hub for AI agents. It stores and syncs what makes your agent yours: its identity (user.md, identity.md, soul.md), its persistent memory, and its session history. Push from one machine, pull to another — your agent wakes up knowing exactly who you are and what you were doing.

---

Why

AI coding agents (Hermes, Claude Code, Codex, OpenCode, …) are getting powerful — but every one of them is trapped on the machine it runs on. Switch laptops, rebuild a container, or lose a cloud instance and your agent's memory evaporates.

Agenome is a thin middle layer. It doesn't replace any agent's native storage — it mirrors it to a portable format that can move between machines and between frameworks.

---

What Agenome syncs

Layer	Format	Framework-agnostic?	Description
Identity (user.md, identity.md, soul.md)	Markdown	✅ Yes	Who you are, how you work, what you value. These files are injected directly into any agent's system prompt.
Memory	JSON	✅ Yes	Persistent key-value memory entries (your preferences, environment facts, tool quirks). Agenome normalizes these into a common schema.
Sessions	JSONL	⚠️ Best-effort	Full conversation transcripts. Cross-framework session sync is the hardest part — each framework structures conversations differently. Agenome stores the raw transcript + framework tag, and provides framework-specific import/export adapters.

---

Roadmap

Phase 1 — MVP (now)
  └─ Git backend (store state in a git repo)
  └─ Hermes adapter (push/pull Hermes sessions, memory, identity)

Phase 2 — Server backend
  └─ FastAPI server with SQLite + blob storage
  └─ Same CLI, different backend flag (--backend git|server)

Phase 3 — Cross-framework
  └─ Claude Code adapter
  └─ Codex adapter
  └─ OpenCode adapter
  └─ Framework-agnostic session schema

---

Architecture

                   ┌─────────────────────┐
                   │     agenome CLI      │
                   │  push | pull | list  │
                   └─────────┬───────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
    ┌─────────▼────────┐        ┌──────────▼──────────┐
    │   Git Backend    │        │  Server Backend      │
    │  (git repo as    │        │  (FastAPI + SQLite   │
    │   state store)   │        │   + S3 blob store)   │
    └──────────────────┘        └─────────────────────┘
              │                             │
    ┌─────────▼────────┐                    │
    │  ~/.agenome/     │                    │
    │  (local mirror)  │                    │
    └──────────────────┘                    │
                                            │
    ┌───────────────────────────────────────▼────┐
    │                Agent Hub                     │
    │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
    │  │ Hermes   │  │ Claude   │  │  Codex   │  │
    │  │ Adapter  │  │ Adapter  │  │ Adapter  │  │
    │  └──────────┘  └──────────┘  └──────────┘  │
    └────────────────────────────────────────────┘

Two backends, two use cases:

Backend	Best for	Trade-off
Git	Solo dev, zero ops, versioned history	No real-time sync between machines
Server	Team use, multi-machine, always-on	Needs hosting, more complex setup

Both backends expose the same CLI surface. Switching is a config line.

---

Quick Start (planned)

# Install
pip install agenome

# Init — creates ~/.agenome/config.yaml, sets up git repo or server URL
agenome init

# Push current Hermes state
agenome push --agent hermes

# Pull to another machine
agenome pull --agent hermes

# List what's stored
agenome list

---

Identity files (user.md / identity.md / soul.md)

These are the framework-agnostic core of Agenome. Every agent — Hermes, Claude Code, Codex — ultimately reads a system prompt. Agenome makes sure the same identity files land in every agent's prompt, regardless of framework.

~/.agenome/identity/
├── user.md        # Who you are: name, role, context, preferences
├── identity.md    # What kind of assistant: tone, personality, boundaries
└── soul.md        # Core values, principles, what matters to you

Each adapter reads these and injects them into the agent-specific configuration (Hermes memory, Claude CLAUDE.md, Codex instructions, …).

---

Session schema design goals

Sessions are the hardest cross-framework problem. Agenome takes a pragmatic approach:

1. Store the raw transcript in its original format + a framework tag
2. Normalize to a common schema on read (best-effort): role, content, timestamp, tool_calls
3. Search across agents — "find where I discussed authentication" searches all frameworks

// Normalized session entry
{
  "id": "20260520_143052_a1b2c3",
  "framework": "hermes",
  "created_at": "2026-05-20T14:30:52Z",
  "messages": [
    {"role": "user", "content": "Fix the login bug"},
    {"role": "assistant", "content": "…", "tool_calls": [...]}
  ],
  "metadata": {
    "model": "deepseek-v4-pro",
    "provider": "opencode-go"
  }
}

---

Project structure

agenome/
├── README.md
├── pyproject.toml
├── src/agenome/
│   ├── __init__.py
│   ├── cli.py                 # push, pull, list, init, status
│   ├── core/
│   │   ├── __init__.py
│   │   ├── store.py           # Abstract storage backend interface
│   │   ├── git_store.py       # Git-backed storage
│   │   └── api_store.py       # Server-backed storage
│   ├── adapters/
│   │   ├── __init__.py
│   │   ├── base.py            # Abstract agent adapter
│   │   └── hermes.py          # Hermes-specific adapter
│   ├── models/
│   │   ├── __init__.py
│   │   ├── memory.py          # Memory entry normalization
│   │   ├── session.py         # Session schema & conversion
│   │   └── identity.py        # Identity file management
│   └── server/
│       ├── __init__.py
│       └── api.py             # FastAPI server (Phase 2)
├── config/
│   └── example.yaml           # Example configuration
└── tests/
    └── test_hermes_adapter.py

---

Design principles

1. Agent does not need to know Agenome exists. It's a sidecar process.
2. Identity files are the universal layer. Markdown files work everywhere.
3. Never mutate originals. Push reads from the agent, pull writes to the agent. Agenome's own store is the source of truth.
4. Git is the MVP backend. Zero infrastructure, version history free, works offline.
5. Server comes second. When you need multi-machine sync without manual push/pull.

---

Progress

Legend: ✅ Done   🔶 In Progress   ⬜ Planned   ❌ Blocked

Phase 1 — MVP: Git Backend + Hermes Adapter

#	Task	Status	Notes
1.1	Project scaffold (pyproject.toml, structure)	✅	pip install -e . works
1.2	Data models (AgentState, Session, MemoryEntry, IdentityFile)	✅	Pydantic v2, framework-agnostic schema
1.3	Abstract StoreBackend interface	✅	Git + future Server share same contract
1.4	GitStore: repo init, config, commit	✅	Auto-sets repo-local user.name/email
1.5	GitStore: push_identity / pull_identity	✅	Round-trip verified
1.6	GitStore: push_memories / pull_memories	✅	JSON normalization per framework
1.7	GitStore: push_session / pull_sessions	✅	Per-session JSON, batched commit
1.8	GitStore: push_state / pull_state	✅	Full AgentState snapshot
1.9	GitStore: list_states	✅	Table display of all frameworks in hub
1.10	Abstract AgentAdapter interface	✅	Framework-agnostic contract
1.11	HermesAdapter: read/write identity (SOUL.md, USER.md)	✅	Parses ~/.hermes/memories/ and ~/.hermes/SOUL.md
1.12	HermesAdapter: read/write memories (MEMORY.md § format)	✅	Normalizes to MemoryEntry, round-trip safe
1.13	HermesAdapter: read sessions from state.db (SQLite)	✅	Full messages + metadata, 71 sessions verified
1.14	CLI: agenome init	✅	Creates ~/.agenome/ config + Git hub + identity templates
1.15	CLI: agenome push (--agent, --identity/--memory/--sessions)	✅	Batched session commit (50 sessions → 1 commit)
1.16	CLI: agenome pull (--agent, --identity/--memory/--sessions)	✅	Restores identity + memory to agent; sessions read-only
1.17	CLI: agenome list	✅	Rich table of stored states
1.18	CLI: agenome status	✅	Local vs Hub comparison table
1.19	README + README_CN	✅	Bilingual, vision + architecture + roadmap
1.20	Unit tests: HermesAdapter	✅	60 tests, covers memory/identity/sessions/full state
1.21	Unit tests: GitStore	✅	35 tests, covers push/pull/roundtrip for all data types
1.22	Unit tests: CLI commands	✅	12 tests, covers init/push/pull/list/status/help
1.23	Push to PyPI (pip install agenome)	⬜
1.24	Edge case: empty hermes home (no state.db)	⬜	Graceful handling needed
1.25	Edge case: git repo with existing remotes	⬜	Merge vs overwrite strategy
1.26	Session write-back to agent (pull --sessions)	⬜	Currently read-only; need safe restore
1.27	agenome pull diff preview (dry-run)	⬜	Show what would change before applying

Phase 2 — Server Backend

#	Task	Status	Notes
2.1	FastAPI server scaffold	⬜
2.2	SQLite schema for AgentState	⬜
2.3	REST endpoints: push / pull / list	⬜
2.4	API key auth	⬜
2.5	ApiStore backend (implements StoreBackend)	⬜
2.6	CLI: agenome init --backend server	⬜
2.7	Blob storage for large session files (S3/MinIO)	⬜
2.8	Docker Compose one-liner deploy	⬜
2.9	Sync conflict detection (last-write-wins + warning)	⬜

Phase 3 — Cross-Framework

#	Task	Status	Notes
3.1	Claude Code adapter (CLAUDE.md, sessions)	⬜
3.2	Codex adapter	⬜
3.3	OpenCode adapter	⬜
3.4	Framework-agnostic session schema v1	⬜	role, content, timestamp, tool_calls
3.5	Cross-framework session search	⬜
3.6	agenome merge — merge memory from two frameworks	⬜	Dedup by content hash

Polish & DX

#	Task	Status	Notes
P.1	Shell completions (bash, zsh)	⬜
P.2	CI/CD (GitHub Actions: lint, test, publish)	⬜
P.3	agenome doctor — check agent/config/store health	⬜
P.4	agenome watch — auto-push on session end (filesystem watcher)	⬜
P.5	Config validation on init	⬜
P.6	Incremental push (only new sessions since last push)	🔶	Partial — state snapshot tracks last sync timestamp

---

Last updated: 2026-05-20

License

MIT