# Signet Architecture Understanding - 2026-02-16

## Core Concept

Signet provides a **universal agent identity** that lives at `~/.agents/`. This is the agent's home directory, analogous to how each AI platform has its own home:

- `~/.claude` → Claude Code's home
- `~/.config/opencode` → OpenCode's home
- `~/.openclaw` → OpenClaw's home
- **`~/.agents` → the agent's home** (universal standard)

## Development vs Installed Client

- `~/signet/signetai/` = source code repository (what we're building)
- `~/.agents/` = installed client (what users get after running `signet setup`)

The npm package bundles everything needed and creates the ~/.agents directory structure on install.

## Architecture

```
Master Agent Profile (database in ~/.agents)
              │
              ▼
        Signet Daemon
              │
    ┌─────────┼─────────┬─────────┐
    ▼         ▼         ▼         ▼
~/.claude  ~/.agents  ~/.codex   etc.
CLAUDE.md  AGENTS.md  AGENTS.md
    │         │         │
    ▼         ▼         ▼
Claude Code OpenClaw  Codex
```

## Key Principles

1. **Database is source of truth** - Markdown files are generated projections
2. **Harness adapters** - Each platform has an adapter that:
   - Knows the native config path (e.g., `~/.claude/CLAUDE.md`)
   - Generates harness-specific format from database
   - Parses changes back to database
3. **Hook adapters** - Platform-specific integrations that work within each tool's constraints while providing the same functionality (memory persistence, context injection)
4. **Not all tools look at ~/.agents by default** - We must play into each platform's limitations and regenerate their native config files

## Work Done This Session

- Created `~/signet/signetai/packages/cli/templates/` with bundled memory scripts
- Scripts included: memory.py, embeddings.py, hybrid_search.py, vector_store.py, export_embeddings.py, regenerate_memory.py, migrate.py, migrations/
- Updated CLI setup wizard to copy templates to `~/.agents/` and initialize database with schema v5
- Templates include AGENTS.md.template, MEMORY.md.template, config.yaml.template

## Next Steps

- Implement harness adapters (Claude Code, OpenClaw, OpenCode)
- Build the daemon that watches database and regenerates configs
- Test full setup flow for new users