Memory Contracts

Jidoka memory is a small set of data contracts and a single Jidoka.Memory.Store behaviour. The agent spec declares a memory policy; the runtime turns that policy into recall and write requests; a pluggable store answers those requests. This guide documents each struct and the store interface so that custom stores (Postgres, Redis, vector DB, etc.) can interoperate without guesswork.

When To Use This

• Use this guide when you need the exact shape of a memory entry, recall, or write to build a store, replay tool, or audit query.
• Use this guide when wiring Jidoka.Memory.Store.InMemory into tests.
• Do not use this guide as a memory tutorial. The high-level workflow lives in Runtime And Harness.

Prerequisites

• You have read Agent Spec Contract, in particular Jidoka.Agent.Spec.Memory.
• You can build and run a Jidoka turn.

Quick Example

A complete memory round-trip uses the in-memory store and the three core contracts: WriteRequest, RecallRequest, RecallResult.

alias Jidoka.Memory.{Entry, RecallRequest, WriteRequest, Store}

{:ok, pid} = Jidoka.Memory.Store.InMemory.start_link([])
store = {Jidoka.Memory.Store.InMemory, pid: pid}

entry = Entry.new!(agent_id: "time_agent", content: "User prefers Chicago time")
{:ok, _write} = Store.write(store, WriteRequest.new!(entry: entry))

request =
  RecallRequest.new!(
    agent_id: "time_agent",
    scope: :agent,
    query: "preferred timezone",
    limit: 3
  )

{:ok, recall} = Store.recall(store, request)
length(recall.entries)
#=> 1

Concepts

╭──────────────────╮     ╭───────────────────╮     ╭──────────────────╮
│ Spec.Memory      │────▶│ Runtime           │────▶│ Memory.Store     │
│ (policy)         │     │ assembles recall  │     │ (behaviour)      │
╰──────────────────╯     ╰─────────┬─────────╯     ╰────────┬─────────╯
                                   ▼                        ▼
                          ╭──────────────────╮      ╭──────────────────╮
                          │ RecallRequest    │      │ RecallResult     │
                          │ WriteRequest     │      │ WriteResult      │
                          ╰──────────────────╯      ╰──────────────────╯

Spec.Memory is policy (definition data). Stores are supplied per run through harness options. The runtime negotiates the conversation by emitting RecallRequest and WriteRequest structs and reading RecallResult / WriteResult back.

Fields

Jidoka.Memory.Entry

Durable memory entry available to prompt assembly.

Jidoka.Memory.RecallRequest

Request sent to a store before prompt assembly.

Jidoka.Memory.RecallResult

Result returned by Memory.Store.recall/2.

Jidoka.Memory.WriteRequest

Request to upsert one entry.

Jidoka.Memory.WriteResult

Acknowledgement returned by Memory.Store.write/2.

Jidoka.Memory.Store Behaviour

Three callbacks define the store contract. A store is a module or {module, opts} tuple.

Top-level helpers Memory.Store.recall/2, Memory.Store.write/2, and Memory.Store.list_entries/1 normalize the {module, opts} shape before dispatching.

Common Patterns

• Reuse Entry.new!/1 to generate ids. The default "mem_…" id is enough for most stores; supply your own only when integrating with an external primary key.
• Carry routing data in metadata. Stores should ignore unknown keys, so feel free to thread tenant ids, embedding model names, or trace ids through any of the request/result maps.
• Use scope to gate session-only memory. RecallRequest.scope: :session with a session_id lets a store filter cross-session data without app code.
• Keep stores small. Implementing the three callbacks is enough; the runtime handles policy, capture, and injection.

Testing

The in-memory store is the canonical test fixture. It exercises the full contract without touching disk or network.

setup do
  {:ok, pid} = Jidoka.Memory.Store.InMemory.start_link([])
  {:ok, store: {Jidoka.Memory.Store.InMemory, pid: pid}}
end

test "writes and recalls a single entry", %{store: store} do
  entry = Jidoka.Memory.Entry.new!(agent_id: "demo", content: "hello")

  assert {:ok, _} =
           Jidoka.Memory.Store.write(store,
             Jidoka.Memory.WriteRequest.new!(entry: entry)
           )

  request =
    Jidoka.Memory.RecallRequest.new!(
      agent_id: "demo",
      query: "hello",
      limit: 5
    )

  assert {:ok, recall} = Jidoka.Memory.Store.recall(store, request)
  assert [%{content: "hello"}] = recall.entries
end

Troubleshooting

Reference

• Jidoka.Memory - public type aliases.
• Jidoka.Memory.Entry
• Jidoka.Memory.RecallRequest
• Jidoka.Memory.RecallResult
• Jidoka.Memory.WriteRequest
• Jidoka.Memory.WriteResult
• Jidoka.Memory.Store - behaviour.
• Jidoka.Memory.Store.InMemory - reference store.
• Jidoka.Agent.Spec.Memory - policy that drives recall.

Related Guides

• Agent Spec Contract - memory policy lives on the spec.
• Runtime And Harness - how memory is wired into a turn.
• Turn And Effect Contracts - where recall results land on Turn.State.