kala.memory — io.github.anusornc/kala 0.3.1

The memory layer: an agent's runs held as datoms under the memory spine.

One turn is exactly one transaction, attributed to its session by tx-meta (:memory/session on the transaction entity); a session is an ordinary entity resumed by its :memory.session/id; derivations cite their turn via :memory/source. The spine is the only schema this namespace owns — all content attributes are the developer's registered vocabulary, rejected by the transactor when unregistered.

Every function here is uniform over both access modes: pass a peer connection or a client connection from kala.client. Errors ride the library-wide :kala/error contract with :memory/* kinds; they are raised in the caller's process and never cross the wire.

context clj

(context db {:keys [as-of cap corrections?] :or {corrections? true}})

The context document — one readable-EDN belief-state map, the thing a harness stuffs into a prompt:

(context db {:cap 5 :as-of 43})

:current is memory's content, newest first, capped in facts (:cap, default 50, ceiling 500); over cap, :truncated names the dropped attributes and never re-lists their values. :corrections is the full trail of the entities shown — superseded values and retractions, :now nil when retraction resolved them; :corrections? false omits the section. :turns is every session's [t turn] pairs, bounded at the pin. The document is store-wide (sessions are provenance, not partitions) and never carries a wall clock.

history clj

(history db {:keys [scope entity session attrs from-t to-t as-of limit]})

The trail of one scope, in t order:

(history db {:scope :entity :entity eid :attrs #{:proj/name}}) (history db {:scope :session :session "run-42"})

Entity scope is the correction trail — every assertion and retraction of one entity, optionally narrowed to attributes. Session scope is the provenance trail — every datom the session's turns wrote, joined through the spine. Entries are {:e :a :v :t :added}, optionally bounded by the pin and inclusive :from-t/:to-t — the pin bounds the trail itself, in both access modes. Capped like query.

install clj

(install conn)

Register the memory spine on conn. Idempotent: returns the transaction report when the spine was installed, nil when it was already present. Call it explicitly at setup — the schema stays visible where the developer's own vocabulary is registered.

pull clj

(pull db eid {:keys [pattern as-of] :or {pattern (quote [*])}})

Shape one entity into a document — the whole entity by default:

(pull db eid {:as-of 43}) (pull db eid {:pattern [:proj/name]})

All or nothing: a document over the serialized-size cap refuses the read with :memory/result-too-large and a narrower-pattern hint, so a pulled entity is never partially shaped. A nonexistent entity is nil.

query clj

(query db query-form {:keys [args as-of limit] :or {args []}})

Run a Datalog query over memory — joins included:

(query db '[:find ?v :in $ ?e :where [?e :proj/deploy-command ?v]] {:args [[:proj/kala]] :as-of 43})

The db binds $; {:args [...]} feeds the rest of :in in order. List results are capped at :limit (default 100, hard ceiling 1000) and any capped answer carries :truncated. Scalar and collection find shapes pass through uncapped. kala's own error kinds surface verbatim.

record clj

(record conn session tx-data)

Record one turn of memory: tx-data becomes exactly one transaction, attributed to session (an entity id or a :memory.session/id string) by tx-meta. Returns the turn's coordinates:

{:t 60 ; the turn's t — address every read with it :turn 4 ; its 1-based ordinal within the session :tx 9700001 ; the transaction entity id — citable as :memory/source :tempids {"p" 12} ; your tempids, resolved :datoms 3} ; datoms the turn wrote, attribution and stamp included

Inside tx-data, the string "datomic.tx" in a ref position cites the current turn; earlier turns are cited by the :tx returned then, and a map form keyed "datomic.tx" carries your own tx-meta. A cardinality-one add over a different current value is a correction — the old belief stays in history; [:db.fn/cas e a old new] is the guarded variant for concurrent sessions.

session clj

(session conn)

(session conn {:keys [id] :or {id (str (java.util.UUID/randomUUID))}})

Open a memory session, returning its entity id:

(session conn) ; a fresh generated id (session conn {:id "run-42"}) ; your own id

Re-opening an id returns the SAME session entity — the id is a unique-identity attribute, so resume is an upsert and provenance never forks across processes.

spine clj

The provenance spine: the only idents kala.memory registers. Anything else in a memory transaction is the developer's vocabulary.

turns clj

(turns db session {:keys [as-of limit]})

The step index of a session — the way "step 12" becomes a t:

(turns db "run-42" {:as-of 43})

{:session <id> :turns [[t ordinal txInstant] ...]} — one triple per turn in t order, bounded by :as-of, capped like query. The wall clock rides here, honestly: the context document keeps it out, this door does not.