Identity, memory, and soul for AI agents.
Agents forget everything between sessions. Flair gives them a persistent sense of self — who they are, what they know, how they think — backed by cryptographic identity and semantic search.
Built on Harper. Single process. No sidecars. Zero external API calls for embeddings.
Every agent framework gives you chat history. None of them give you identity.
An agent that can't remember what it learned yesterday, can't prove who it is to another agent, and loses its personality on restart isn't really an agent. It's a stateless function with a system prompt.
Flair fixes that:
- Identity — Ed25519 key pairs. Agents sign every request. No passwords, no API keys, no shared secrets.
- Memory — Persistent knowledge with semantic search. Write a lesson learned today, find it six months from now by meaning, not keywords.
- Soul — Personality, values, procedures. The stuff that makes an agent that agent, not just another LLM wrapper.
Flair is a native Harper v5 application. Harper handles HTTP, persistence (RocksDB), and application logic in a single process.
Agent ──[Ed25519-signed request]──▶ Flair (Harper)
├── Auth middleware (verify signature)
├── Identity (Agent + Integration tables)
├── Memory (write → auto-embed → store)
├── Soul (permanent personality/values)
└── Search (semantic + keyword, ranked)
No external dependencies at runtime. Embeddings are generated in-process using nomic-embed-text via a Harper plugin. Model runs on CPU or GPU (Metal, CUDA). No API calls, no sidecar processes, no network hops.
Every agent has an Ed25519 key pair. Requests are signed with agentId:timestamp:nonce:METHOD:/path and verified against the agent's registered public key. 30-second replay window with nonce deduplication.
Memories are automatically embedded on write using nomic-embed-text (768 dimensions). Search by meaning:
# Write a memory
flair memory write "Harper v5 sandbox blocks node:module but process.dlopen works"
# Find it later by concept, not exact words
flair memory search "native addon loading in sandboxed runtimes"
# → [0.67] Harper v5 sandbox blocks node:module but process.dlopen worksNot all memories are equal:
| Durability | Delete | TTL | Use Case |
|---|---|---|---|
permanent |
❌ Rejected | None | Identity, values, core knowledge |
persistent |
✅ Allowed | None | Daily logs, project context |
standard |
✅ Allowed | None | Working memory (default) |
ephemeral |
✅ Allowed | 24h | Scratch space, temp context |
Subscribe to memory or soul changes via WebSocket/SSE. Useful for dashboards, cross-agent sync, or audit trails.
One Flair instance serves any number of agents. Each agent has its own keys, memories, and soul. Agents can't read each other's data without explicit access grants.
- Node.js 20+ (24+ recommended)
# Install
npm install -g @tpsdev-ai/flair
# Bootstrap a Flair instance (installs Harper, creates database, starts service)
flair init
# Register your first agent
flair agent add mybot --name "My Bot" --role assistant
# Check everything is working
flair statusThat's it. Your agent now has identity and memory.
npm install @tpsdev-ai/openclaw-flairAdd to your openclaw.json:
{
"memory": {
"provider": "@tpsdev-ai/openclaw-flair"
}
}Your agent will automatically remember things between sessions and recall them by meaning.
# Write a memory
flair memory add --agent mybot --content "Harper v5 sandbox blocks bare imports"
# Search by meaning, not keywords
flair memory search --agent mybot --q "native module loading issues"
# Set personality
flair soul set --agent mybot --key role --value "Security reviewer, meticulous and skeptical"
# Back up everything
flair backup --admin-pass "$FLAIR_ADMIN_PASS"
# Restore from backup
flair restore ./flair-backup-2026-03-15.json --admin-pass "$FLAIR_ADMIN_PASS"Agents can pull their full context on startup via the BootstrapMemories endpoint:
curl -H "Authorization: TPS-Ed25519 ..." \
-X POST http://localhost:9926/BootstrapMemories \
-d '{"agentId": "mybot", "maxTokens": 4000}'Returns soul + recent memories + relevant context as a formatted block. Bounded context regardless of total memory size.
flair/
├── src/cli.ts # CLI: init, agent, status, backup, grant
├── config.yaml # Harper app configuration
├── schemas/
│ ├── agent.graphql # Agent + Integration + MemoryGrant tables
│ └── memory.graphql # Memory + Soul tables
├── resources/
│ ├── auth-middleware.ts # Ed25519 verification + agent scoping
│ ├── embeddings-provider.ts # In-process nomic embeddings
│ ├── Memory.ts # Durability enforcement + auto-embed
│ ├── Soul.ts # Permanent-by-default personality
│ ├── MemorySearch.ts # Hybrid semantic + keyword search
│ ├── MemoryBootstrap.ts # Cold start context assembly
│ └── MemoryFeed.ts # Real-time memory changes
├── plugins/
│ └── openclaw-memory/ # @tpsdev-ai/openclaw-flair plugin
└── SECURITY.md # Threat model + auth documentation
- Harper-native — No Express, no middleware frameworks. Harper IS the runtime.
- In-process embeddings — Native nomic-embed-text (768 dimensions) via llama.cpp. Runs on CPU or GPU (Metal, CUDA). No API calls, no OpenAI key needed.
- Schema-driven — GraphQL schemas with
@table @exportauto-generate REST CRUD. Custom resources extend behavior (durability guards, auto-embedding, search). - Zero admin tokens on disk — Admin credentials come from the
HDB_ADMIN_PASSWORDenvironment variable only. Never stored on the filesystem.
flair initYour data stays on your machine. Best for personal agents, dev teams, and privacy-first setups. Flair runs as a single Harper process — no Docker, no cloud, no external services.
Run Flair on a VPS or cloud instance. Agents connect over HTTPS:
# On the server
flair init --port 9926
# Agents connect with:
FLAIR_URL=https://your-server:9926 flair agent add mybotGood for teams with multiple machines or always-on agents.
Managed multi-region deployment via Harper Fabric. Data replication, automatic failover, web dashboard. Enterprise scale without ops overhead.
See SECURITY.md for the full security model, threat analysis, and recommendations.
Key points:
- Ed25519 cryptographic identity — agents sign every request
- Collection-level data isolation — agents can't read each other's memories
- Admin credentials never stored on disk — environment variables only
- Key rotation via
flair agent rotate-key - Cross-agent access requires explicit grants
bun install # Install dependencies
bun run build # Compile TypeScript → dist/
bun test # Run unit + integration testsIntegration tests spin up a real Harper instance on a random port, run the test suite, and tear down. No mocks for the database layer.
Note: Flair uses Harper v5, currently in beta. We run it in production daily and track upstream closely. Pin your Harper version.
Flair is in active development and daily use. We dogfood it — the agents that build Flair use Flair for their own memory and identity. 7 agents, 150+ memories, running continuously since March 2026.
What works:
- ✅ Ed25519 agent identity and auth
- ✅ CLI: init, agent add/remove/rotate-key, status, backup/restore, grant/revoke
- ✅ Memory CRUD with durability enforcement
- ✅ In-process semantic embeddings (768-dim nomic-embed-text, Metal GPU)
- ✅ Hybrid search (semantic + keyword)
- ✅ Soul (permanent personality/values)
- ✅ Real-time feeds (WebSocket/SSE)
- ✅ Agent-scoped data isolation
- ✅ Cold start bootstrap
- ✅ OpenClaw memory plugin
What's next:
- Encryption at rest (opt-in AES-256-GCM per memory)
- Pluggable embedding backends (OpenAI, Cohere, local)
- Harper Fabric deployment (managed multi-office)
- Scheduled automatic backups