Memory Structure

The Memory Bus is the backbone of Artemis City’s knowledge infrastructure, mediating all read/write operations between agents and the persistent memory stores. In v2, we introduced a rigorous Memory Bus Consistency & Synchronization API that guarantees updates propagate reliably to both the graph store (Obsidian vault) and the vector index (Supabase) with minimal latency. This section describes the write-through protocol, read query hierarchy, consistency guarantees, and performance characteristics of the updated memory bus.

2.1 Write-Through Memory Sync Protocol

Write Path: When an agent commits new knowledge (e.g. creating or updating a Markdown note), the memory bus performs an atomic write-through to both the Obsidian vault and the Supabase vector store. The operation is orchestrated as a single transaction: the bus first generates an embedding for the knowledge node and upserts it into the vector index, then writes the note and metadata to the Obsidian vault, and finally confirms the write back to the agent. This ensures that vector search data is always updated before the knowledge becomes visible to agents, maintaining consistency. The entire commit sequence is acknowledged only after both the graph file and vector index have been successfully updated, so agents never see a partial write.

Agent Write Request → Memory Bus → [Parallel: Obsidian Write + Supabase Embed] →

Wait for Both → Confirm to Agent

To support durability, the memory bus uses a write-ahead log (WAL) and batching mechanism. All pending writes are logged so that if a crash occurs mid-transaction, the system can recover to a consistent state. Writes may be batched for efficiency — e.g. accumulate writes for up to 100 ms or 50 operations before flushing — and periodic checkpoints are taken (every 1000 operations or 60 seconds) to cap recovery time. These measures improve throughput while guaranteeing that either all parts of a batched update are applied or none are (atomicity).

If any step of the multi-stage write fails (for example, the vector DB is temporarily unreachable), the memory bus will rollback the transaction and retry according to a backoff policy. This prevents divergent states between the vault and index. Together, the write-through protocol and WAL provide strong write consistency — all agents see the same latest knowledge, and no acknowledged write is ever lost.

2.2 Read Path and Consistency Guarantees

Hierarchical Read Protocol: To serve queries efficiently, the memory bus implements a tiered lookup strategy. A read request (e.g. when an agent searches or references knowledge) progresses through three levels:

Exact Lookup (O(1)): Check for an exact note match by unique ID or title hash — this is a constant-time hash map lookup and returns immediately if found.

Structured Search (O(log n)): If no exact match, perform a structured keyword search across the knowledge graph’s indices (e.g. tags, titles, links) — leveraging sorted indices for logarithmic-time retrieval.

Vector Similarity (O(n)): As a fallback, execute a semantic vector similarity search against the Supabase pgvector index to find relevant notes by content embedding. This is the most expensive step, treated as last resort when other methods fail to find an answer.

By default, the memory bus returns results with staleness metadata indicating the sync status between the Obsidian vault and Supabase index. The system guarantees read-your-writes consistency: an agent will immediately see its own writes on subsequent reads. To further optimize common reads, Artemis City employs aggressive caching on the memory bus. Exact lookups and recent query results are cached in-memory, yielding fast (~50 ms) responses for frequent queries. The cache is invalidated on writes to maintain correctness, and a cache hit rate >80% is targeted for repeat queries. This layered approach provides both speed and completeness in querying the knowledge base.

2.3 Conflict Handling and Consistency

In a concurrent multi-agent environment, it is possible for two agents to attempt overlapping writes (e.g. editing the same note) at nearly the same time. The memory bus includes a concurrent write resolution mechanism to handle such conflicts deterministically. The strategy is a last-write-wins arbitration: each knowledge node update carries a timestamp, and the latest timestamp prevails if write contention is detected. In practice, writes acquire an optimistic lock; if a race is detected (a node was modified since read), the later write is allowed but the conflict is logged for audit.

To strengthen this, each knowledge node can maintain a simple version vector or incrementing version number. If an agent’s write is based on an outdated version, the memory bus can detect it and either reject the write or queue it for manual review. For semantic conflicts (where the content changes are non-trivial merges), Artemis City defers to a manual resolution queue — flagging the node for a human or higher-level agent to reconcile the changes. These measures ensure the knowledge graph remains logically consistent and that no update is lost without notice. All conflicts and resolutions are recorded in the governance log for transparency.