API Reference

LongMemory is person-scoped, temporally-aware preference memoryfor AI agents. It answers one question fast and cheaply: given who's involved and when it is, what do we know about what they want?

All bodies are JSON. Unknown fields are rejected with a 400; max body size is 1 MB. Times are RFC3339 — send an offset to control local time-of-day semantics (2026-07-08T20:00:00+05:30→ “evening”).

The core path makes zero LLM calls and zero embedding calls. Preferences are typed assertions; recall is indexed SQL plus deterministic ranking. Extraction, when you want it, piggybacks on the agent call you already make.

Build and run the engine:

go build -o bin/longmemory ./cmd/longmemory
./bin/longmemory        # :8080, ./longmemory.db, open single-tenant mode

Remember two preferences:

curl -s localhost:8080/v1/ops -d '{
  "owner_id": "u1",
  "ops": [
    {"op":"assert","domain":"health","key":"allergy",
     "value":"peanuts","polarity":"rule"},
    {"op":"assert","domain":"comms","key":"channel","value":"slack",
     "polarity":"like","context":{"time_of_day":["morning"]}}
  ]}'

Recall before your agent acts:

curl -s localhost:8080/v1/recall -d '{"owner_id": "u1"}'

The response carries a prompt-ready context_block:

### Memory (as of 2026-07-22 09:15, tue morning)
- You: [RULE] allergy: peanuts | likes slack (@morning)

Two modes, chosen by whether LM_ADMIN_KEY is set.

Errors are {"error":{"code":"...","message":"..."}} with status 400/401/404/429/500/501. Rate limiting is a per-tenant token bucket (rate_rps, burst 2×) returning 429 plus Retry-After.

Apply a batch of operations atomically — all or nothing, up to 200 ops. This is the write path, and the endpoint your agent'semit_memory_ops tool output goes to.

{
  "owner_id": "u_42",
  "ops": [
    {"op":"person_upsert","name":"Priya","relation":"wife","aliases":["wife"]},
    {"op":"assert","person":"wife","domain":"food","key":"diet",
     "value":"vegetarian","polarity":"rule"},
    {"op":"assert","person":"self","domain":"food","key":"diet","value":"no sugar",
     "polarity":"rule","valid_until":"2026-07-31T23:59:59Z"},
    {"op":"retract","person":"self","domain":"food","key":"spice_tolerance"}
  ]
}

Operations

assert fields

Response

{"results":[
  {"index":0,"action":"person_created","person_id":"p_01hv…"},
  {"index":1,"action":"created","assertion_id":"a_01hv…","superseded":["a_01hu…"]}
]}

Actions: created, reinforced, retracted, person_created, person_updated, merged, forgotten, not_found (selector matched nothing — the batch still succeeds).

Everything known about the mentioned persons, valid now (or at at), matching the moment's context, ranked — plus a rendered context block. Pure SQL and arithmetic: no LLM, ~0.78 ms.

{
  "owner_id": "u_42",
  "persons": ["self", "wife"],        // default ["self"]; "*" = everyone
  "domains": ["food", "dining"],      // default all; "general" always included
  "at": "2026-07-08T20:00:00+05:30",  // default server now
  "location": "home",                 // optional
  "occasion": "date_night",           // optional
  "max_per_person": 12,               // default 12
  "token_budget": 800                 // context_block budget, default 800
}

Response

{
  "persons": [
    {"ref":"wife",
     "person":{"id":"p_…","name":"Priya","relation":"wife"},
     "assertions":[
       {"id":"a_…","key":"diet","value":"vegetarian","polarity":"rule",
        "score":1.1,"effective_confidence":1.0,"provenance":"stated"}
     ]}
  ],
  "unresolved": [
    {"ref":"rohit","candidates":[{"id":"p_…","name":"Rohit Sharma"},
                                 {"id":"p_…","name":"Rohit Verma"}]}
  ],
  "context_block": "### Memory (as of 2026-07-08 20:00, wed evening)\n- You: …",
  "at":"2026-07-08T14:30:00Z", "time_of_day":"evening", "day":"wed",
  "elapsed_ms":0.8
}

Ranking

Rules sort first and survive token-budget trimming. Everything else ranks by provenance weight × effective confidence, plus a context-specificity bonus and a recency term. Inferred facts decay on a 180-day half-life and drop out below 0.35 confidence. Identical inputs always produce identical output.

Log raw events (≤500 per batch). Recognized payload fields distill into behavioural signals; three observations of the same pattern within 90 days materialize an inferred preference — time-of-day scoped when ≥80% of the observations agree. No LLM involved.

{
  "owner_id": "u_42",
  "episodes": [{
    "kind": "order_completed",
    "domain": "food",
    "persons": ["self"],
    "text": "Ordered Chicken Biryani from Meghana Foods",
    "payload": {"restaurant":"Meghana Foods",
                "items":[{"name":"Chicken Biryani","cuisine":"biryani"}],
                "total":540},
    "occurred_at": "2026-07-07T20:05:00+05:30"
  }]
}

Recognized payload fields

Anything else in the payload is stored but ignored for inference. Only text is full-text indexed.

Lexical full-text search over logged episodes and active assertions. Multi-word queries AND their terms, falling back to OR when that finds nothing.

{"owner_id":"u_42","query":"goa trip","types":["episode"],
 "kinds":["message"],"domains":[],"limit":10}

{"hits":[{"type":"episode","id":"e_…","text":"…","kind":"message",
          "occurred_at":"…","rank":1.9}],"elapsed_ms":0.6}

LongMemory also implements Anthropic's client-side memory_20250818 tool contract, so Claude can manage its own notes and have them be durable, multi-user and searchable. Forward each memory tool_use block's input verbatim, plus an owner_id.

POST /v1/memory
{"owner_id":"u1","command":"create",
 "path":"/memories/user.md","file_text":"name: AJ\n"}

→ {"content":"File created successfully at: /memories/user.md",
   "is_error":false}

Commands: view, create, str_replace, insert, delete, rename. Paths are jailed under /memories. Command-level failures return HTTP 200 with is_error: true — relay that straight back as the tool result.

When you just want to store a sentence and search it later — no schema, no paths. The server derives a path from the content, so re-sending identical text is idempotent. 1–100 items per batch.

{"owner_id":"u_42","memories":[
  {"text":"Allergic to shellfish; carries an epipen.","topic":"health"},
  {"text":"Works at Google as a software engineer."}
]}

The server files each memory under an optional topic folder (default notes) plus a content hash, so identical text always lands on the same path:

{"stored":[
  {"path":"/memories/health/9f2a41c83d10.md"},
  {"path":"/memories/notes/5b11d02e77a4.md"}
]}

Retrieve with POST /v1/memory/search. Configure LM_EMBED_MODEL to add a local static-embedding arm for paraphrase matches; without it, search is keyword-only and honest about it.

Text in, ops out, using the server's own Anthropic key (LM_ANTHROPIC_KEY; model LM_ANTHROPIC_MODEL, default claude-haiku-4-5-20251001). Returns 501 when not configured — by design.

{"owner_id":"u_42",
 "text":"my wife Priya is vegetarian and I'm off sugar this month",
 "at":"2026-07-07","apply":true}

Response: {"ops":[...], "results":[...]} — results only with apply:true. This is the one endpoint that calls a model; the piggyback contract above is the recommended integration and costs nothing.

Available when LM_ADMIN_KEY is set. A tenant is the trust boundary — give each customer their own tenant; never share one key across mutually untrusted users.

Also: GET /healthz (no auth) and GET /v1/stats for tenant-scoped counts.

The longmemory package bundles the compiled binary and a stdlib-only client. No dependencies, no server to start — the engine boots on loopback and stops with your process.

pip install longmemory

from longmemory import LongMemory

mem = LongMemory()                       # binary auto-starts on 127.0.0.1

mem.person("Priya", relation="wife")
mem.remember("wife", "food", "diet", "vegetarian", polarity="rule")
mem.remember("self", "food", "cuisine", "biryani", polarity="like",
             context={"time_of_day": ["evening"]})

print(mem.context(persons=["self", "wife"], domains=["food"]))
# ### Memory (as of 2026-07-08 20:00, wed evening)
# - You: likes biryani (@evening)
# - Priya (wife): [RULE] diet: vegetarian

Methods

Pass base_url to talk to an engine you already run, and api_key for multi-tenant mode. Prebuilt for macOS and Linux; elsewhere it raises EngineNotFound and you build from source.

Apple M2, single process. Reproduce with make bench.

Scaling

Recall is an indexed lookup bounded by one owner's set, so total corpus size barely matters. Measured with the recalled owner held at a realistic 240 assertions while the database grew around it:

~0.5 KB per assertion on disk; ~30 MB RSS. If a single owner ever accumulated hundreds of thousands of assertions, that owner's recall would grow — cost tracks the size of the set being recalled, not the table.