Memory Architecture and Notes

Private memory lanes, restart durability, model-switch behavior, and distributed knowledge sharing in one place.

Memory Architecture

Built for precise task memory, durability across restarts, and clean shared knowledge exchange over Kafka.

Private Agent Memory

Per agent and per thread memory stores task facts, decisions, and open work context.

• Scoped to session and resource lanes
• Semantic retrieval from embeddings
• Low-noise indexing policy

Durability and Recovery

State persists in local timeline and memory stores so restarts do not drop tasks or heartbeats.

• Restart-safe session continuity
• Embedding runtime health endpoints
• First embedding enable does not wipe memory

Shared Knowledge Pool

Agents publish structured facts over Kafka with source, confidence, and version metadata.

• Claw identity for machine-to-machine trust
• Proposal, vote, and decision events
• Quorum voting when 3 or more claws participate

End-to-End Memory Flow

ingest embed store retrieve share vote finalize

Model switch rule: if a previously used embedding model changes, memory vectors are wiped before reindex. Adding the first embedding model later does not wipe existing text records.

Cascading Protocol (Gated Subtasks)

Full protocol details, state machine infographic, and operational guidance are documented in CoT Cascading Protocol.

Kafka Knowledge Pool: How It Works

The shared knowledge pool is the distributed memory layer used when multiple claws collaborate. It is event-based and runs on Kafka with typed envelopes (proposal, vote, decision, fact, presence, capabilities). Each message includes identity and trace metadata (clawId, instanceId, traceId, idempotencyKey) so receivers can deduplicate and audit every state change.

ID Model and Anti-Tampering Controls

ID fields are used as a trust and replay-control layer:

• clawId: stable node identity for a claw in the group.
• instanceId: runtime instance identity for that claw process.
• traceId: end-to-end correlation id across proposal, votes, decision, and fact events.
• idempotencyKey: unique apply key for a logical knowledge event.

Controls implemented now:

1. Strict envelope validation
   Required fields are enforced before apply (schemaVersion, type, traceId, timestamp, idempotencyKey, clawId, instanceId).
2. Replay and duplicate blocking
   idempotencyKey is recorded in knowledge_idempotency with a unique constraint, so the same event is applied once.
3. One-vote-per-claw rule
   Votes are keyed by (proposal_id, claw_id) in storage, so one claw cannot stack multiple votes on one proposal.
4. Fact version integrity
   Facts must start at v1 and then advance sequentially (+1 only). Regressions, gaps, and mismatched stale updates are rejected as conflict or stale.
5. Governance gate
   Governed message types (proposal, vote, decision, fact) are blocked when governance is disabled.
6. Self-loop suppression
   A claw ignores envelopes that claim its own local clawId, preventing local re-apply loops.
7. Audit trail
   Accepted and rejected apply outcomes are written with trace metadata to timeline events for forensic review.

Important scope note:

• These controls prevent many tampering effects inside the app flow (duplicate replay, invalid structure, vote inflation, version rewrites).
• Transport/auth hardening still depends on Kafka security posture (TLS, SASL, topic ACLs, producer identity controls).
• Knowledge envelopes are not currently signed end-to-end at message level, so broker and network trust boundaries still matter.

Why 3+ Claws for Voting

Voting only becomes meaningful at 3 or more participating claws.

• With 1 claw, there is no consensus. It is only a local assertion.
• With 2 claws, ties and bilateral bias are common.
• With 3 or more claws, majority outcome is possible and resistant to one wrong or stale node.

Practical effect:

• 3 claws: majority threshold is 2.
• 5 claws: majority threshold is 3.
• Quorum should be based on currently active and healthy participants, not total registered claws.

This is why governance mode requires quorum logic before a fact is promoted as shared truth.

End-to-End Governance Flow

1. A claw publishes a proposal with a clear statement and tags.
2. Other claws publish vote events (yes or no) with optional reason.
3. A coordinator path emits decision after quorum and majority are reached (or expired/rejected).
4. If approved, a versioned fact is published and applied to shared memory.
5. Claws consume the new fact and can use it for routing, delegation, and prompt context.

Capability Discovery and Skill Sharing Use Case

Example with 4 claws:

• claw-1 has filesystem access to production log paths.
• claw-2 has read-only database access.
• claw-3 has incident triage and runbook skills.
• claw-4 is the coordinator handling incoming user requests.

Flow:

1. Each claw publishes capabilities to Kafka, for example:
   • claw-1: logs.read:/var/log/app/*
   • claw-2: db.read:orders,customers
   • claw-3: incident.runbook:v2
2. claw-4 receives a task: “Why did checkout fail in the last hour?”
3. claw-4 routes sub-tasks based on announced capabilities:
   • ask claw-1 for log error windows
   • ask claw-2 for failed transaction rows
   • ask claw-3 to map findings to runbook actions
4. A new reusable conclusion is proposed:
   • “Error E142 with DB timeout pattern maps to mitigation M7”
5. 3+ active claws vote.
6. Majority decision publishes a versioned fact.
7. Next incident can be solved faster by any claw because the fact is now in the shared pool.

This keeps agent memory precise:

• private memory stays task-local and focused
• shared pool only accepts promoted, voted knowledge
• noisy one-off chat does not become distributed truth

Topic and Contract References

For envelope schema and payload contracts, see:

• Knowledge Contracts
• Group and Kafka Communication Operations