Crate kibisis 

kibisis

Local-first encrypted cognitive memory vault with atomic concurrency leases.

Autonomous AI agents running parallel execution loops frequently corrupt shared state when attempting concurrent read-modify-write cycles against flat files or SQLite databases. Kibisis solves this by providing:

1. Structured Memory Entities: Key-value memory storage partitioned by category, with monotonic version tracking and soft-archival capabilities.
2. Single-Writer Multi-Reader (SWMR) Leases: Atomic distributed leasing with strictly increasing fencing tokens to eliminate stale-worker race conditions.
3. Cryptographic Envelopes: Envelope schema definitions for local ChaCha20-Poly1305 authenticated encryption at rest.

Architecture Overview

• MemoryVault: Trait defining storage operations (MemoryVault::put, MemoryVault::get, MemoryVault::search, MemoryVault::archive).
• InMemoryMemoryVault: Thread-safe reference implementation protected by mutex locks.
• LeaseCoordinator: Trait defining atomic lease acquisition, renewal, and release.
• InMemoryLeaseCoordinator: Reference lease coordinator using monotonic fencing tokens.

Quick Start

use std::time::Duration;
use kibisis::{InMemoryLeaseCoordinator, InMemoryMemoryVault, LeaseCoordinator, MemoryEntity, MemoryVault};

// 1. Store and retrieve memory records
let mut vault = InMemoryMemoryVault::new();
let note = MemoryEntity::new("agent_state", "step_4", "Compiled unit test binary");
let saved = vault.put(&note).expect("Put must succeed");
assert_eq!(saved.version, 1);

let retrieved = vault.get("agent_state", "step_4").expect("Get must succeed").unwrap();
assert_eq!(retrieved.content, "Compiled unit test binary");

// 2. Coordinate concurrent access with fencing tokens
let mut coordinator = InMemoryLeaseCoordinator::new();
let ttl = Duration::from_secs(30);

let lease = coordinator.acquire("shared_database", "worker_alpha", ttl)
    .expect("Worker alpha acquires lease");
assert_eq!(lease.fencing_token, 1);

// Competing worker is rejected while lease is held
assert!(coordinator.acquire("shared_database", "worker_beta", ttl).is_err());

// Worker alpha releases lease
assert!(coordinator.release(&lease).expect("Release must succeed"));

Structs

EncryptedEnvelope

Cryptographic envelope schema for encrypted records at rest.

InMemoryLeaseCoordinator

In-memory reference implementation of LeaseCoordinator with atomic fencing tokens.

InMemoryMemoryVault

In-memory reference implementation of MemoryVault.

Lease

Distributed concurrency lease granting single-writer privileges.

MemoryEntity

Structured cognitive memory record stored in the vault.

SearchResult

Search match returned from memory queries.

Enums

CryptoError

Errors returned during encryption or decryption operations.

LeaseError

Errors returned during lease acquisition, renewal, or release.

VaultError

Errors returned by memory vault storage operations.

Constants

VERSION

Traits

CryptoEnvelope

Trait defining symmetric encryption and decryption of payload slices.

LeaseCoordinator

Trait defining atomic single-writer lease coordination.

MemoryVault

Core trait defining persistent cognitive memory storage.