Metadata-Version: 2.4
Name: agenome
Version: 0.1.1
Summary: Agent genome hub — sync AI agent identity, memory, and sessions across machines and frameworks
Project-URL: Homepage, https://github.com/XiongDaowen/agenome
Project-URL: Repository, https://github.com/XiongDaowen/agenome
Project-URL: Issues, https://github.com/XiongDaowen/agenome/issues
Author-email: XiongDaowen <xiongdaowen@users.noreply.github.com>
License: MIT
Keywords: ai-agent,claude-code,hermes,identity,memory,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: server
Requires-Dist: aiosqlite>=0.19; extra == 'server'
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: httpx>=0.24; extra == 'server'
Requires-Dist: sqlalchemy>=2.0; extra == 'server'
Requires-Dist: uvicorn>=0.23; extra == 'server'
Description-Content-Type: text/markdown

# 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)

```bash
# 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 &nbsp; 🔶 In Progress &nbsp; ⬜ Planned &nbsp; ❌ 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) | ✅ | v0.1.0 published at https://pypi.org/project/agenome/ |
| 1.24 | Edge case: empty hermes home (no state.db) | ✅ | Graceful: returns empty results, clear error messages |
| 1.25 | Edge case: git repo with existing remotes | ✅ | Detects remote on init; `--sync`/`--fetch` flags for multi-machine sync |
| 1.26 | Session write-back to agent (pull --sessions) | ✅ | Writes sessions to state.db; skip existing, --overwrite to replace |
| 1.27 | `agenome pull` diff preview (dry-run) | ✅ | --dry-run shows identity/memory/sessions diff 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-06-02

## License

MIT
