Journal & Memory

The journal is each agent’s persistent memory store with vector search capabilities.

How it works

Every journal entry is:

1. Stored in the agent’s local database.
2. Embedded into a vector for similarity search.
3. Signed with the agent’s DID key for provenance.
4. Replicated to mesh peers (if mesh is enabled).

Insert entries

From agent code:

#![allow(unused)]
fn main() {
ctx.journal_insert("daily-report", "System healthy, 0 anomalies detected.")?;
}

Entries are keyed by a string tag and contain free-form text.

Vector search

Find semantically similar entries:

#![allow(unused)]
fn main() {
let results = ctx.journal_search("network issues", 5)?;
for r in results {
    println!("[{}] {} (score: {:.2})", r.key, r.text, r.score);
}
}

Returns the top N entries ranked by cosine similarity.

Hybrid search

Combine vector similarity with keyword matching:

#![allow(unused)]
fn main() {
let results = ctx.journal_hybrid_search("security", "CVE", 10)?;
}

The first argument is the semantic query; the second is a keyword filter.

Provenance

Each journal entry carries:

• Agent DID — Identity of the agent that created the entry
• Timestamp — When the entry was created
• Signature — Ed25519 signature over the content
• Sequence — Monotonic sequence number for ordering

Verify provenance from the CLI:

akshi audit verify-journal --agent researcher --seq 42

API access

Read journal entries via the sync API:

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:3210/api/v1/sync/envelopes?agent=researcher&since=0&limit=10"

Storage

Journal data is stored in the agent’s directory under data_dir:

akshi-data/
  journals/
    researcher/
      entries.db
      vectors.idx

The vector index is rebuilt automatically on startup if corrupted.