• Multi-tenant identifier management: Supporting multiple AIDs within a single agent instance
• Isolated keystore management: Each identifier maintains its own cryptographic material in a separate Hab
• Coordinated operations: Facilitating operations that span multiple identifiers (such as multisig coordination)
• Resource sharing: Common infrastructure (witnesses, watchers, network connections) shared across identifiers

Key Features & Capabilities

Hab Management Architecture

The Habery implements a collection-based architecture where:

1. Each Hab is identifier-specific: A Hab stores all key material and data for exactly one AID, providing strong isolation between identifiers
2. LMDB-based persistence: Uses LMDB (Lightning Memory-Mapped Database) for efficient, ACID-compliant storage
3. Python object model: Implemented as Python data structures (objects) that provide programmatic access to identifier operations

Storage Technology: LMDB

The choice of LMDB as the underlying storage engine provides several critical capabilities:

• Memory-mapped file access: Extremely fast read operations through direct memory mapping
• ACID transactions: Ensures consistency even in the face of crashes or concurrent access
• Compact storage: Efficient B-tree structure minimizes disk space usage
• Zero-copy reads: Data can be accessed directly from memory-mapped regions without copying
• Multi-version concurrency control (MVCC): Readers never block writers, writers never block readers

This storage architecture is particularly well-suited for KERI's requirements:

• Append-only KEL storage: LMDB's B-tree structure efficiently handles sequential writes
• Fast signature verification: Quick access to public keys and key state data
• Event log queries: Efficient retrieval of specific events or event ranges
• Witness receipt storage: Compact storage of receipts and KERL data

Multi-AID Support

A critical architectural evolution documented in the 2022 KERI Community Meeting notes shows the Habery architecture enabling multiple AIDs per KERIpy instance:

November 29, 2022 Meeting Report:

"Habery changes propagated through command line utilities and agent. Architecture split: separated shared resources from AID-specific code. Support for multiple AIDs per KERIpy instance."

This architectural split represents a fundamental shift from single-identifier agents to multi-tenant systems, enabling:

• Shared witness pools: Multiple identifiers can use the same witness infrastructure
• Common network resources: Single network stack serves multiple identifiers
• Unified agent interface: One agent process manages multiple identifiers
• Resource efficiency: Reduced memory and process overhead compared to per-identifier agents

Integration with KERI Command Line Interface (KLI)

The Habery architecture directly supports the KLI (KERI Command Line Interface), as documented in the November 1, 2022 meeting:

"KLI now supports new Habery architecture"

This integration means that command-line operations can:

• Reference specific Habs by name or identifier
• Perform operations across multiple identifiers in a single command sequence
• Manage keystore lifecycle (creation, backup, recovery) at the Habery level
• Coordinate multi-signature operations involving multiple Habs

REST API and Agent Architecture

The Habery architecture underlies the KERIA agent's REST API, enabling:

• Per-identifier endpoints: API routes scoped to specific Habs
• Swagger UI documentation: Auto-generated API documentation reflecting Habery structure
• Stateless operations: Each API call can target a specific Hab without maintaining session state
• Concurrent access: Multiple clients can interact with different Habs simultaneously

Architecture and Design Patterns

Separation of Concerns

The Habery implements a clear separation between shared and identifier-specific resources:

Shared Resources (Habery Level):

• Network connections and protocol handlers
• Witness pool configurations
• Watcher network connections
• OOBI resolution infrastructure
• CESR parsing and serialization utilities

Identifier-Specific Resources (Hab Level):

• Private key material and key pairs
• KEL (Key Event Log) storage
• Key state tracking
• Delegation relationships
• ACDC credential storage
• TEL (Transaction Event Log) data

Keystore Isolation

Each Hab maintains cryptographic isolation:

• Separate key material: Private keys for one identifier never accessible from another Hab's context
• Independent rotation schedules: Each identifier manages its own key rotation independently
• Isolated pre-rotation commitments: Next key digests stored per-Hab
• Per-identifier thresholds: Multi-sig thresholds configured independently

Habery in Multi-Signature Workflows

The Habery architecture is particularly important for multi-signature identifier management:

Multi-Sig Coordination:

1. Each participant in a multi-sig group maintains their own Hab for their signing keys
2. The Habery coordinates the collection of partial signatures
3. Threshold verification occurs at the Habery level
4. The resulting multi-sig events are stored in each participant's Hab

Example from GAR Setup Documentation:

The GLEIF Authorized Representative (GAR) setup guide demonstrates Habery usage in multi-sig scenarios:

"Uses the multisig-shell.sh interactive tool to configure the group multisig identifier. Adds local participant aliases and remote participant identifiers."

This workflow requires:

• Each GAR maintains a local single-sig Hab
• The Habery coordinates the multi-sig inception across participants
• The resulting group identifier is stored in each participant's Habery
• Subsequent operations reference both local and group Habs

Usage Patterns

Habery Initialization

Based on the GAR setup documentation, Habery initialization follows this pattern:

1. Environment setup: Configure GLEIF_HOME or equivalent environment variables
2. Keychain creation: Generate or load keychain secrets
3. Salt and passcode configuration: Initialize cryptographic parameters
4. Habery instantiation: Create the Habery instance with configuration

Creating a New Hab

When creating a new identifier, the process involves:

1. Hab allocation: Habery allocates a new Hab instance
2. Key generation: Generate initial key pairs within the Hab
3. Inception event creation: Create the first event in the KEL
4. Witness configuration: Associate witnesses with the identifier
5. LMDB storage: Persist the Hab state to the database

Accessing Existing Habs

The Habery provides access patterns for retrieving existing identifiers:

• By name/alias: Human-readable identifier names
• By AID prefix: Direct lookup by cryptographic identifier
• By role: Query Habs by their role in the system (e.g., delegation relationships)

Habery in Delegation Scenarios

The QVI delegation workflow documented in the GAR setup guide shows Habery usage in delegation scenarios:

Delegator Habery:

• Contains the Hab for the delegating identifier (e.g., GLEIF External AID)
• Stores the delegation event that authorizes the delegate
• Maintains the seal linking to the delegate's inception

Delegate Habery:

• Contains the Hab for the delegated identifier (e.g., QVI)
• References the delegator's prefix in the inception event
• May use a proxy AID for communication before delegation approval

Integration with did:webs Resolution

The did:webs resolver roadmap documents how the Habery integrates with DID resolution:

Static DID Asset Generation

"Creates 'did.json' and 'keri.cesr' files based on a local AID's state stored in the local keystore (Habery)."

This integration means:

1. DID document generation: The Habery provides the current key state for DID document construction
2. CESR stream export: The complete KEL can be exported from the Hab as a CESR stream
3. Designated aliases support: The Habery manages alias attestations that populate the alsoKnownAs field

Dynamic DID Asset Generation

"Utilizes HTTP endpoints to dynamically generate 'did.json' and 'keri.cesr' files based on the current real-time state of an AID."

The Habery enables dynamic generation by:

• Providing real-time access to current key state
• Serving as the authoritative source for KEL events
• Managing witness receipt aggregation for KERL construction

Security Considerations

Keystore Protection

The Habery implements several security measures:

1. Encrypted storage: LMDB databases can be encrypted at rest
2. Access control: Habery-level authentication before Hab access
3. Key isolation: Private keys never leave their Hab context
4. Secure deletion: Proper key material zeroization when Habs are removed

Multi-Tenant Security

In multi-tenant scenarios, the Habery must ensure:

• Tenant isolation: One tenant cannot access another's Habs
• Resource limits: Prevent resource exhaustion attacks
• Audit logging: Track access to sensitive operations
• Rate limiting: Prevent brute-force attacks on keystores

Performance Characteristics

LMDB Performance Benefits

The LMDB-based Habery provides:

• Fast reads: Memory-mapped access eliminates copy overhead
• Efficient writes: B-tree structure optimizes sequential writes (ideal for append-only KELs)
• Scalability: Handles thousands of Habs in a single Habery
• Low latency: Sub-millisecond access times for key material

Scaling Considerations

As the number of Habs grows:

• Memory usage: Each Hab requires memory for in-memory caching
• File descriptors: LMDB uses file descriptors that may need OS-level tuning
• Backup strategies: Large Haberies require efficient backup mechanisms
• Sharding: Very large deployments may require Habery sharding across multiple processes

Relationship to KERIA Agent

The KERIA agent documentation describes the Habery as central to agent architecture:

"An agent in KERIA terms, is an instance of a keystore (Hab) that runs in a given instance of the KERIA agent server."

This means:

• Agent = Habery + Network Stack: The agent is essentially a Habery with network interfaces
• Multi-tenant agents: One KERIA instance serves multiple Habs via its Habery
• API scoping: REST API endpoints are scoped to specific Habs within the Habery

Future Directions

Based on the did:webs resolver roadmap, future Habery enhancements may include:

Remote AID Management

"Import of DID Assets for Remote AIDs: Future functionality will enable importing CESR streams for remote AIDs, allowing the local dynamic DID asset generation system to securely handle external identifiers."

This suggests Habery evolution toward:

• Remote Hab caching: Storing verified KELs for remote identifiers
• Trust boundary management: Clear separation between local and remote Habs
• Verification caching: Storing verification results for remote identifiers

Enhanced Access Control

"Strict Dynamic DID Asset Hosting for Remote AIDs: Plans to implement access controls on HTTP DID asset generation endpoints, restricting dynamic generation to only an explicitly allowed set of AIDs."

This implies Habery-level access control lists:

• Allowlists: Explicit lists of AIDs authorized for dynamic generation
• Role-based access: Different access levels for different Hab operations
• Audit trails: Comprehensive logging of Hab access patterns

Implementation Notes

The Habery represents a pragmatic implementation choice in the Python KERI ecosystem that balances:

• Performance: LMDB provides excellent performance for KERI's access patterns
• Simplicity: Python object model makes Habery easy to use and extend
• Scalability: Multi-tenant architecture supports large-scale deployments
• Security: Strong isolation between identifiers prevents cross-contamination

While the Habery is specific to KERIpy/KERIA, the architectural pattern it represents - separating shared infrastructure from identifier-specific storage - is likely to appear in other KERI implementations as they mature and support multi-identifier scenarios.

The Habery is not a protocol-level concept but rather an implementation best practice that has emerged from the reference implementation's evolution toward production-ready, multi-tenant agent architectures.