kala-mcp

Kala · กาล

Kala (Pali–Sanskrit–Thai: "time, era") — a time-traveling Datalog database. An independent, clean-room, open-source (EPL-1.0) reimplementation of Datomic's architecture in Clojure on the JVM: a transactor that serializes writes into an append-only log, an embedded peer library with in-memory indexes, a remote client library, Datalog queries, the pull API, and time travel — every db value is the database as of one t.

Status: v1 complete, published to [Clojars](https://clojars.org/io.github.anusornc/kala) — behavioral suite green across {peer, client} × {memory, file}; the query-engine optimization wave (#15), the original-Datomic bench adapter (#19), and the Datahike cross-check have landed; the roadmap lives in the issue tracker.

Build and test

clojure -M:test          # full matrix: {peer, client} x {memory, file} + backend suites

e2e.sh # project E2E: transactor SIGKILL crash-recovery over real

processes, release jar, demo, web demo, MCP server

(all|transactor|release|demo|web|mcp)

clojure -T:build jar # build the release jar (EPL-1.0 notices included) clojure -T:build mcp-jar # build the kala-mcp server artifact (separate jar)

The behavioral suite runs twice per cycle — peer (embedded) and client (remote, over the wire against a live transactor) — on both storage backends, which is what enforces access-mode and storage-backend parity. Entity navigation and seek scans are peer-only; clients use pull. Tests run at two seams: the behavioral API suite and the storage-protocol contract suite per adapter.

Demo

clojure -M:demo

A single-file walkthrough (demo/kala/demo.clj) proving the public surface end to end: schema, list- and map-form transactions, Datalog (predicates, joins, recursive rules, aggregates), pull, entity navigation (forward and reverse refs), compare-and-swap including its structured failure, stored transaction functions, time travel (as-of, history, with), durable file storage across a reopen, and a remote client over the transactor wire. Every claim is asserted — a mismatch aborts with a nonzero exit, so a run that prints ALL PROOFS PASSED means the behavior is real.

Web demo

clojure -M:web              # http://127.0.0.1:8090  (or: clojure -M:web 9000)

The same demo as an interactive app: a JVM server (web/kala/web.clj) embedding Kala as a peer — JDK's built-in HttpServer, zero dependencies — seeding the people fixture into file storage and serving a small no-build browser UI. Write your own Datalog queries, transact EDN ops (failures come back as the project's error kinds), slide reads across t with as-of, browse the raw datoms and the full history, then hit Reopen from disk and watch every acked transaction survive. EDN in, EDN out — responses carry pr-str'd values. The server binds 127.0.0.1; tx-data is read with clojure.edn (same documented no-sandboxing posture as ADR-0004).

Monitor

clojure -M:monitor --store /var/data/agent-memory        # own a transactor

clojure -M:monitor --attach 127.0.0.1:4334:SECRET # ride a running one clojure -M:monitor --store /tmp/try.edn-dir --seed # a seeded scratch store

The second web app: the store's transactions drawn as a knowledge graph of entity and turn nodes (web/kala/monitor.clj). The monitor speaks client mode and nothing else (ADR-0012) — every read travels the wire to a live transactor, the peer path does not exist in its code, and starting a transactor on the target store is the prerequisite (the --store form starts an owned one for you and connects over loopback). A kala.backup log export is viewed by restoring it into a fresh store directory first (see Backup and migration) and pointing --store at that; --seed records a small deterministic memory store through the client connection for a first look.

One shared view — filter, as-of, selection — through three switchable view modes: force soup (physics, relation exploration), turn rail (the t-order spine with entity lanes), and bipartite columns (always-labeled structure). Follow renders each commit as the transactor lands it; freeze pins one belief state and resuming jumps to head, never replays. The as-of slider travels the total order; click a turn node for the datoms it transacted, an entity node for its correction trail. Hand-rolled SVG, zero dependencies, binds 127.0.0.1, read-only — the endpoints are graph reads, a head ping, and two drilldowns.

Memory for agents

Kala ships a memory layer (kala.memory, inside the core jar) and an MCP server (kala.mcp, its own artifact) that exposes it to any agent harness.

The vocabulary is the domain's: memory is agent-run knowledge held as datoms under a three-ident provenance spine; a session is one run recording memory; a turn is exactly one transaction; and the context document is the belief-state map an LLM reads. One turn = one transaction, attributed to its session by tx-meta — provenance holds by construction, because the layer writes the attribution, never the caller.

(require '[kala.api :as api] '[kala.memory :as memory])

(def conn (api/connect {:storage :file :path "/var/data/agent-memory"})) (memory/install conn) ; idempotent: the spine (def s (memory/session conn {:id "run-42"})) ; resume by id, upsert (memory/record conn s [[:db/add "p" :proj/deploy-command "make deploy"]]) ; => {:t 60, :turn 1, :tx 9700001, :tempids {"p" 12}, :datoms 3}

(memory/context (api/db conn) {:cap 5}) ; the belief-state document (memory/turns (api/db conn) "run-42" {}) ; step N -> t, then read as-of t

Reads are the doors — query (Datalog, joins included), pull, history (entity and session scopes), turns — every one addressable :as-of t, every list capped with the cap visible (:truncated), because a silently shortened answer would misstate what the agent believed. Corrections are data: a cardinality-one re-assertion supersedes the old belief into history, and context's :corrections section shows the full trail of the entities it shows you.

Backup and migration

The storage log exports as EDN and restores into any backend — entity ids and t replay identically, values ride tagged literals, and the append-only guard means an import can extend a store, never overwrite one. See docs/backup-and-migration.md.

MCP server

echo '{:conn {:storage :file :path "/var/data/agent-memory"}

:session "my-agent"}' > mcp.edn clojure -M:mcp mcp.edn

Six tools over stdio, JSON-RPC: context (call this first — the capped, correction-annotated belief state; with-t stamps every :current tuple with its asserting t, min-t bounds it to recent facts), record (one turn; the server owns the session, so tx-data carries no attribution), recall (Datalog with joins; the data-only predicate allowlist includes the lexical matchers includes?/starts-with?/ends-with? — regex stays out: agent-written patterns would be a ReDoS surface on the transactor), read (one entity, current or as-of), history (correction/provenance trails), turns ("step 12" becomes a t). EDN in, EDN out — arguments that carry structure are EDN strings, results are readable EDN, and errors are the store's own error maps under the MCP isError flag. The harness→server hop is same-user local; when the server reaches a remote transactor it authenticates with the shared token like any client (see ADR-0006).

No Clojure CLI at hand? One executable jar runs the server:

clojure -T:build mcp-uberjar          # once, from a checkout

java -jar target/kala-mcp-*-standalone.jar mcp.edn

server.json (MCP registry metadata) sits at the repo root. The official registry has no Maven/Clojars package type, so the listing rides the "oci" type: docker/Dockerfile wraps the standalone jar, and its label carries the registry's ownership annotation. Publishing is three user-authenticated commands (bump server.json's version and the image tag together on release):

clojure -T:build mcp-uberjar

docker build -t ghcr.io/anusornc/kala-mcp:0.5.0 -f docker/Dockerfile . && docker push ghcr.io/anusornc/kala-mcp:0.5.0 mcp-publisher login github && mcp-publisher publish

Benchmark

clojure -M:bench                          # core suite: kala, DataScript, Datahike

clojure -M:bench-datomic --suite=datomic # Datomic suite: kala, DataScript, original Datomic clojure -M:bench 5000 20000 # custom entity counts

Two suites, never one classpath: Datahike's and com.datomic/peer's data_readers.clj both claim the db/id and db/fn tags, so the JVM refuses to boot with both jars present. Both suites cross-check that kala, DataScript, and the third engine return identical query results, then print latency tables. Dependencies (datascript, datahike, com.datomic/peer) are bench-only.

Latency rows report the mean plus p50/p95/p99 of per-operation times: after a warmup, every call is timed with System/nanoTime — GC pauses land in p95/p99, which is honest for a database. Workloads: bulk ingest and 100 single-entity updates as wall clock, plus three read shapes (simple pattern, filtered + input, join) and a point read. The final section times the same peer engine on durable file storage against memory — the durability cost: reads are comparable (indexes are rebuilt in memory), writes pay the fsync-before-ack. A kala-only last section prices contention: 1–8 concurrent client connections transacting through one transactor (memory storage, per-op percentiles per concurrency level), which is what serialization through the single writer costs.

Methodology: engine setup (connection, schema transact — noticeable for original Datomic's peer startup) happens before any timing and is excluded from every number. Ingest is cold single-pass wall clock over batched transactions. The datoms-in-store totals include engine-internal bookkeeping (schema and transaction datoms), so they differ by engine; the cross-check compares query results, not totals. The Datomic engine is peer-only; its API deviations from the other engines are recorded in bench/kala/bench/datomic_peer.clj, the Datahike engine's in bench/kala/bench/datahike_engine.clj.

Launch a transactor

echo '{:port 4334 :storage :file :path "/var/data/mydb"}' > transactor.properties.edn

clojure -M:transactor transactor.properties.edn

or, idempotent for agents after reboot:

bin/start-transactor transactor.properties.edn

Then connect remotely with kala.client/connect — see docs/wire-protocol.md for the protocol. Adding :compact true to the config lets clients trigger compaction over the wire; the default refuses (:compact/disabled, ADR-0010).

For multi-agent shared memory (one transactor, many sessions), see docs/agent-ops.md: bin/start-transactor, bin/kala-mem (client calls without booting MCP per invocation), and clearer :transact/unknown-attribute hints.

Release

Kala is published to Clojars:

io.github.anusornc/kala     {:mvn/version "0.5.0"}   ; the database + memory layer

io.github.anusornc/kala-mcp {:mvn/version "0.5.0"} ; the MCP server (separate artifact)

Releases are tag-triggered: pushing a v* tag runs the behavioral matrix as a final gate, builds the jar from the tag version, deploys to Clojars (deps-deploy with the `CLOJ