Technical reference

An event log for agents, with recall and provenance

memspine is an HTTP server that stores an agent's events per tenant and returns them by embedding, by keyword, or by the links between them. The caller supplies the embeddings; the server never calls a model. This page states what each operation guarantees, what was measured and how, and where the service stops.

Version 0.2.2, released 2026-10-08. Linux x86_64 (glibc 2.17 or newer) and macOS arm64.

curl -fsSL https://memspine.com/install.sh | sh

Installs two binaries into ~/.local/bin, checked against a published checksum. No root. First session.

Each row links to the section that gives its conditions.

One tenant's log

Everything below is shown on this log: ten events from a short session between a user and an agent. A turn is something said, a tool_call is something the agent ran, and a fact is something the agent derived and wrote back. The lines at the left are SOURCE_FROM edges. Each fact points at the events it was derived from.

Quickstart

$ curl -fsSL https://memspine.com/install.sh | sh
Downloading memspine-macos-arm64.tar.gz ...
Checksum OK.
Installed memspine-server and memspine-admin to ~/.local/bin

Start the server:
  MEMSPINE_BIND=127.0.0.1:7777 ~/.local/bin/memspine-server

$ MEMSPINE_BIND=127.0.0.1:7777 MEMSPINE_EMBEDDING_DIM=4 \
    ~/.local/bin/memspine-server > memspine.log 2>&1 &
$ sleep 1; curl localhost:7777/health
{"service":"memspine-server","status":"ok","version":"0.2.2"}

$ K="Authorization: Bearer 00000000-0000-0000-0000-000000000042"
$ J="Content-Type: application/json"

$ TURN=$(curl -s localhost:7777/v1/memory/event -H "$K" -H "$J" \
  -d '{"kind":"turn","embedding":[0.9,0.1,0.2,0.1],
    "text":"Ana: we adopted a greyhound called Pixel last weekend"
    }' | jq -r .event_id)

$ curl -s localhost:7777/v1/memory/event -H "$K" -H "$J" \
  -d '{"kind":"fact","embedding":[0.8,0.2,0.1,0.1],
    "text":"Ana owns a dog named Pixel","properties":{
    "source_event_ids":["'"$TURN"'"]}}'
{"event_id":"b5ea3003-7681-4632-a015-5ec4fdec7595"}

$ curl -s localhost:7777/v1/memory/recall -H "$K" -H "$J" \
  -d '{"text":"which dog does Ana have","k":1,"hops":1}' \
  | jq -c '.hits[] | [.kind, .text]'
["fact","Ana owns a dog named Pixel"]
["turn","Ana: we adopted a greyhound called Pixel last weekend"]

Run on macOS arm64 against the published binaries, 2026-10-08. The server takes 384-dimension embeddings unless MEMSPINE_EMBEDDING_DIM says otherwise; this one was started with 4. The last two commands need jq.

The bearer token above is a bare UUID. With no control database, any UUID is a tenant and is also that tenant's key, with read and write access. That mode has no secret and is for local use. memspine-admin init creates the control database, after which only issued keys are accepted.

What an event is

A request body may be 2 MiB for one event and 32 MiB for a batch of up to 1,000.

Events are immutable. To correct one, append the correction and forget the original.

Text and properties of any size within the body limit are stored and read back as sent. From Cypher, up to 16 top-level properties per event can be filtered on by name: booleans, numbers and strings of at most 256 bytes, taken in key order. n.text is null there for text over 4,096 bytes; returning the node gives the whole event.

The server records each tenant's embedding dimension and refuses to open the tenant under a different one once it holds embeddings. It does not record which model produced the vectors, so two models of the same dimension would be mixed without warning.

$ curl -s localhost:7777/v1/memory/event/$F8 -H "$K" | jq .
{
  "event_id": "3dce87e5-4b2c-4cc0-96bc-338ce95f158f",
  "kind": "fact",
  "ts": 1791364515000000,
  "text": "Pixel has a vet appointment at Clinica Arroios on 2026-10-10 at 10:00, booking A-2291",
  "properties": {
    "source_event_ids": [
      "b8533f46-b491-4c20-a078-b0ca2e039926",
      "740c7d03-9b97-4854-8799-6d66524cf3fe"
    ]
  }
}

Operations and what each guarantees

Auth is Authorization: Bearer <key>. The tenant comes from the key and never from the request body. Every response carries x-memspine-trace-id, and the lines the server logs for that request carry the same id.

The write path, and what a crash leaves

Appends within a tenant are serialised; reads run concurrently and do not wait for them. A read can therefore return an event during the moment between its batch and its fsync, before the append has been acknowledged.

$ curl -s localhost:7777/v1/memory/event -H "$K" -H "$J" -d @last.json; echo
{"event_id":"1eb38657-2649-47e6-b082-bf90e6da5c72"}

$ kill -9 $(lsof -tiTCP:7777 -sTCP:LISTEN); sleep 0.3; curl -s -m 2 localhost:7777/health; echo "curl exit $?"
curl exit 7

$ MEMSPINE_BIND=127.0.0.1:7777 MEMSPINE_EMBEDDING_DIM=4 MEMSPINE_DATA_DIR=./data \
    memspine-server > memspine.log 2>&1 &

$ curl -s localhost:7777/v1/memory/event/$E11 -H "$K"; echo
{"event_id":"1eb38657-2649-47e6-b082-bf90e6da5c72","kind":"turn","ts":1791366150000000,"text":"Ana: thanks, that is all for today","properties":{}}

An acknowledged append, kill -9, a restart, and the event read back. Durability was tested this way, by killing the process. It has not been tested by cutting power, and there is one copy on one disk.

A retry

$ curl -s localhost:7777/v1/memory/event -H "$K" -H "$J" \
  -H "Idempotency-Key: turn-0941" -d @turn.json; echo
{"event_id":"af2d5cc8-2a80-583b-b7ed-941419d7a27f"}

$ curl -s localhost:7777/v1/memory/event -H "$K" -H "$J" \
  -H "Idempotency-Key: turn-0941" -d @turn.json; echo
{"event_id":"af2d5cc8-2a80-583b-b7ed-941419d7a27f"}

The same request twice under one Idempotency-Key. The id is a version-5 UUID of the tenant and the key, so both calls return it and one event is stored.

Between tenants

Each tenant is its own database directory, opened on first request. Another tenant's event id returns 404. Each tenant has a token bucket (1,000 requests per second, burst 100) and may have 32 engine calls running or queued; past either it gets a 429. What tenants share is one process, one worker pool and one heap, so a large tenant's scan uses the same cores and memory as its neighbours.

How recall ranks

Given an embedding, events are ranked by cosine similarity. Given text, they are ranked by BM25 over text. Given both, the two rankings are fused by reciprocal rank (Cormack, Clarke and Büttcher, 2009), with ranks counted from 1:

• A keyword candidate scoring under half of the best keyword score is dropped before fusion. Without that floor, every event sharing any word with the query takes a rank, and multi-hop recall fell.
• An event stored without an embedding scores 1 / (60 + rank_keyword), what an embedding-only candidate at the same rank would, so the two kinds interleave.
• Ties go to the candidate the embedding ranked, then to the better single rank, then to the older event.
• kind, since and until filter after ranking; the candidate pool widens fourfold until k events pass or the tenant is exhausted.
• BM25 here has no stemming and no stop-word list, and tokenises ASCII letters and digits only.

On the log

One request, text when is the vet appointment for Pixel and embedding [0.3, 0.9, 0.3, 0.0], asked three ways. Greyed keyword rows fall under the floor.

At these settings the table is the server's own response to the request above. The sliders recompute the fusion in the page with the server's formula. Set the floor to 0 and the weak keyword matches take ranks, including a tool_call that has no embedding.

Hops

After ranking, hops follows SOURCE_FROM edges out from the hits, in both directions, at most 3 steps. It adds at most k events, examines at most 8k, and marks each addition with via, the hit whose walk reached it. The time filters apply to what is reached; the kind filter does not, since the point is to cross from a fact to the turns behind it.

$ curl -s localhost:7777/v1/memory/recall -H "$K" -H "$J" \
  -d '{"text":"vet appointment booking","k":2,"hops":1}' \
  | jq -r '.hits[] | [.kind, .event_id[0:8], (.via // "-")[0:8], .text[0:52]] | @tsv'
fact	3dce87e5	-	Pixel has a vet appointment at Clinica Arroios on 20
fact	c3d7a7af	-	Text Ana the day before the vet appointment
turn	b8533f46	3dce87e5	Ana: book Clinica Arroios for this Saturday at ten
tool_call	740c7d03	3dce87e5	book_vet(Clinica Arroios, 2026-10-10 10:00) -> confi

Cypher over the same edges

$ curl -s localhost:7777/v1/memory/cypher -H "$K" -H "$J" -d '{"query":
  "MATCH (f:Event)-[:SOURCE_FROM]->(s:Event) WHERE f.kind = $kind RETURN f.text, s.kind, s.text",
  "params":{"kind":"fact"}}' | jq -c '.rows[]'
["Ana owns a greyhound named Pixel","turn","Ana: we adopted a greyhound called Pixel last weekend"]
["Ana prefers Saturday appointments","turn","Ana: she needs a vet, somewhere open on Saturdays"]
["Ana prefers Saturday appointments","turn","Ana: book Clinica Arroios for this Saturday at ten"]
["Pixel has a vet appointment at Clinica Arroios on 2026-10-10 at 10:00, booking A-2291","tool_call","book_vet(Clinica Arroios, 2026-10-10 10:00) -> confirmed A-2291"]
["Pixel has a vet appointment at Clinica Arroios on 2026-10-10 at 10:00, booking A-2291","turn","Ana: book Clinica Arroios for this Saturday at ten"]
["Text Ana the day before the vet appointment","fact","Pixel has a vet appointment at Clinica Arroios on 2026-10-10 at 10:00, booking A-2291"]
["Text Ana the day before the vet appointment","turn","Ana: my number is 912 555 019, text me the day before"]

What was measured

Retrieval was scored on LoCoMo (Maharana et al., 2024): 10 long conversations, 1,540 questions in categories 1 to 4. The metric is the fraction of a question's gold evidence turns among the 20 events retrieved per query. 1,536 questions are scored, because four open-domain questions name no evidence. Embeddings are text-embedding-3-small at 384 dimensions.

The server does not extract facts or rewrite queries. In the upper half of the table the benchmark harness does both with gpt-4o-mini, as a client would: it appends dated facts linked to their source turns, and expands each question into subqueries. The lower half stores raw turns and sends the question as the only query. The difference between the halves is the client's work.

Evidence recall@20, LoCoMo, 10 conversations, run 2026-10-07 on the 0.2.1 engine with embeddings and model calls replayed from a cache recorded in June. Marked: fusion's largest gain, the keyword-only collapse on multi-hop questions without query rewriting, and fusion's loss on multi-hop for raw turns.

Is the fused gain real

The keyword weight and the floor were chosen on the first five conversations and checked on the other five.

End-to-end answers

An answer model reads the retrieved events and a judge model marks its answer. This was scored once, on 2026-06-12, on the engine before 0.1.0, with embedding retrieval, gpt-4o-mini as answerer and judge, and about 1,150 answer tokens per question. It has not been re-run on the current engine, where the retrieved context is identical for 93% of questions, and fused retrieval has no such score yet. There is no error bar.

Where it fails: open-domain questions are the weakest category in every row above, and a caller with no embedding model retrieves 0.279 of multi-hop evidence unless it rewrites its queries.

Scale and cost

memspine-bench --mode scale on the 0.2.1 engine, 2026-10-07, an Apple M-series laptop that was not otherwise idle. The engine is called in process, with no HTTP or JSON. Random unit vectors, eight-word texts, two short properties per event; 100 queries, 50 single appends. The sizes in between were not run. The rows bound by fsync (ingest, append, forget, purge) varied several-fold between runs on this machine while other builds were using its disk: a second run at 10,000 events gave a single append of 8.0 ms and a purge of 2.2 s. The search rows did not move.

• Search compares the query with every embedding in the tenant, so its time is linear in tenant size.
• A single append costs one fsync, so unbatched ingest into one tenant is bounded by the disk's fsync rate. The batch route stores 1,000 events per fsync.
• An open tenant holds its embeddings and indexes in memory. A tenant with no request for an hour is closed and reopens at the cold-open cost.
• A purge rewrites the tenant's whole log and blocks that tenant while it runs. At 100,000 events the median was 25 s and the longest 39 s.

Forgetting

A marker file is written before the delete, so a crash between the delete and the purge still purges after restart, whether or not the tenant gets another request.

$ grep -rl "912 555 019" data
data/00000000-0000-0000-0000-000000000042/events.ffs.qlog

$ curl -s -X DELETE "localhost:7777/v1/memory/event/$E9?purge=true" -H "$K"; echo
{"deleted":true,"purged":true}

$ grep -rl "912 555 019" data; echo "grep exit $?"
grep exit 1

$ curl -s -o /dev/null -w "%{http_code}\n" localhost:7777/v1/memory/event/$E9 -H "$K"
404

$ curl -s localhost:7777/v1/memory/event/$F10 -H "$K" | jq -c '.properties'
{"source_event_ids":["af2d5cc8-2a80-583b-b7ed-941419d7a27f","3dce87e5-4b2c-4cc0-96bc-338ce95f158f"]}

$ curl -s localhost:7777/v1/memory/cypher -H "$K" -H "$J" -d '{"query":
  "MATCH (f:Event)-[:SOURCE_FROM]->(s:Event) WHERE f.event_id = $id RETURN s.kind, s.text",
  "params":{"id":"'$F10'"}}' | jq -c '.rows[]'
["fact","Pixel has a vet appointment at Clinica Arroios on 2026-10-10 at 10:00, booking A-2291"]

What remains after a purge:

• Other events that listed the forgotten one in source_event_ids keep its id in their properties, as the last response above shows. The edge is gone.
• If the event was appended under an Idempotency-Key, its id is kept, and nothing else, so that a late retry of that append stores nothing. Cypher patterns without a label see that record; match (n:Event).
• Backups taken before the purge.

Limits

FFS, the storage engine, has no row or time budget for a query and cannot stop one that has started. A query is therefore screened before it runs.

$ curl -s localhost:7777/v1/memory/cypher -H "$K" -H "$J" \
  -d '{"query":"MATCH (a:Event), (b:Event) RETURN count(*)"}'; echo
{"error":"invalid_request","detail":"the query matches two patterns that share no variable, which pairs every row of one with every row of the other. Connect them through a shared variable"}

The screen removes the cheap ways to exhaust the server. It does not bound a query's cost: a pattern through a heavily connected event can still be expensive. Give Cypher only to callers you would let run a full scan.

Use something else if

• a tenant will hold much more than 100,000 events. Search is an exact scan and nothing larger was measured.
• you need a second copy on another host. There is no replication.
• you want the service to embed text, extract facts or summarise. It stores and returns what the caller sends.
• your text is not in ASCII letters and you have no embedding model. Keyword recall will not match it.
• you would expose Cypher to tenants you do not trust.
• you cannot accept a tenant waiting for seconds while a purge runs.
• you need TLS from the server itself. Put it behind a reverse proxy.

Running it

• Run one server per data directory. The server locks the directory and refuses to start while another process holds the lock; two servers writing one tenant's log corrupt it.
• Storage is <data dir>/<tenant uuid>/: FFS's log and checkpoint files and a meta.json recording the embedding dimension. To back a tenant up, copy its directory while the server is stopped.
• SIGTERM drains requests in flight, runs purges that are owed and checkpoints open tenants. A hard kill loses nothing acknowledged; the checkpoint only shortens the next start.
• An open tenant holds about eight file descriptors. The server raises its soft limit to the hard limit at startup and caps open tenants from it: 80 at a limit of 1,024.
• The server speaks plain HTTP. Terminate TLS in a reverse proxy.

What has broken

0.1.0, 0.2.0 and 0.2.1 were all released on 2026-10-07, and 0.2.2 a day later. After 0.2.0, two independent reviews went looking for defects, and each claim was reproduced by a second reviewer before it counted. 0.2.1 and 0.2.2 are the fixes; the last part of the review finished after 0.2.1 had gone out, and found a defect that 0.2.1 itself had introduced. The ones a caller could have met:

The whole list is in changelog.txt. Events forgotten under 0.2.0 left no record of their id, so a retry of one of those keys after upgrading still stores the event.

Tested by 162 Rust tests, 29 in the Python binding's suite and 21 in the TypeScript one. Each change runs formatting, lints with warnings denied, the tests, and a container image that is started and written through. After each publish of this site, the install command above is run on Ubuntu, AlmaLinux 8 and macOS, and the installed binaries append, recall, list and forget an event. The largest tenant measured so far is 100,000 synthetic events.