API Reference

LongMemory is a memory layer for AI. Your app saves what its users say, and before the AI answers, one search returns everything relevant: memories, preferences, past events and document passages, as one block of text ready for the prompt.

Most apps need only three calls: save, search and upload a document. To capture memories from a chat, add the piggyback kit to the AI call your app already makes. All bodies are JSON; unknown fields are rejected with a 400; max body size is 1 MB (25 MB for document uploads).

Start LongMemory from its folder:

./longmemory               # dashboard + API on http://127.0.0.1:8080
./longmemory --no-browser  # API only

1. Save what you learn about a user:

curl -s localhost:8080/v1/memories -d '{
  "user_id": "u1",
  "memories": ["Allergic to shellfish, carries an EpiPen."],
  "preferences": [{"who": "wife", "topic": "diet", "value": "vegetarian", "type": "must", "until": ""}]
}'

2. Upload a document (optional):

curl -s localhost:8080/v1/documents -F knowledge_base="Menus" -F file=@menu.pdf

3. Search before your AI answers:

curl -s localhost:8080/v1/search -d '{"user_id": "u1", "query": "order dinner for me and my wife"}'

Put the contextfield of the response into your AI model's system prompt. That is the whole integration.

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 per tenant (rate_rps, burst 2×) and returns 429 with Retry-After.

One call takes any combination of memories, preferences and events, up to 100 of each. No AI is needed to save.

{
  "user_id": "u_42",
  "memories": ["Allergic to shellfish; carries an EpiPen.",
               {"text": "Works at Google as a software engineer.", "topic": "work"}],
  "preferences": [
    {"who": "self", "topic": "cuisine", "value": "biryani", "type": "like", "until": ""},
    {"who": "self", "topic": "sugar", "value": "none", "type": "must", "until": "2026-12-31"}
  ],
  "events": [{"kind": "order", "text": "Ordered a vegetable biryani", "payload": {"item": "veg biryani"}}]
}

Response

{"stored":[{"path":"/memories/notes/9f2a41c83d10.md"}, …], "preferences":[…], "events":[…]}

A preference that cannot be applied is reported as skipped with the reason; the rest of the save still goes through. Full preference operations (see Advanced) are accepted here too.

One call returns, together, the user's preferences in force now, their most relevant memories and events, and the most relevant document passages, both as ranked results and as context: one block of text ready for the AI model's prompt. No AI call.

{"user_id":"u_42","query":"what should we cook tonight?"}

High accuracy mode

Off by default. Send "accuracy": "high" on a request, or start the server with --accuracy high (LM_ACCURACY=high) to make it the default; a request can still ask for "standard". It returns up to 50 memories unless memories or limit says otherwise, and adds two steps, still with no AI:

• Neighbours: for the top 3 memories, the 2 saved just before and just after each one (within 30 minutes of it) are added right behind it, since a reply often answers a question without repeating its words. Only when 20 or more memories are asked for.
• Dampening:question words found in more than 20% of the user's memories (a name on every line of a chat) are left out of the search, for users with 100 or more memories.

On LoCoMo (all 10 conversations, messages saved as written, no piggyback, 1,536 questions, Claude Sonnet 5.5 answering and grading) it scored 91.5%, against 81.4% for the standard search at 20 memories. It sends more text to the AI (about 2,270 tokens of memories per question) and a search takes about 8 ms typically instead of about 5 ms. Full log

{"user_id":"u_42","query":"what did I say about running?","accuracy":"high"}

Response

{"context":"### Memory (as of 2026-11-04 20:08, wed evening)
- wife: [RULE] diet: vegetarian

### Relevant notes
- ...",
 "preferences":[…],"memories":[{"path":"…","text":"…","relevance":{…}}],
 "events":[…],"documents":[…],"filtered_out":2,"chars":812,"tokens_estimate":205,
 "timings_ms":{"preferences":0.2,"memories":0.7,"events":0.1,"documents":6.1,"total":7.3}}

Upload PDF, Word (.docx), text, Markdown, HTML, CSV or JSON files, up to 25 MB each, as multipart (file, repeatable) or JSON ({"name": "...", "text": "..."}). Searchable immediately; search returns the matching passages with the document name and page.

# shared with every user, in a knowledge base ("General" if omitted)
curl -s localhost:8080/v1/documents -F knowledge_base="HR policies" -F file=@manual.pdf

# one user's own document: searched only for them, deleted with them
curl -s localhost:8080/v1/documents -F user_id=u_42 -F file=@contract.pdf

Uploading a file with the same name to the same place replaces it. Scanned PDFs contain only images of text and cannot be read without OCR.

LongMemory never calls an AI model. Your app already calls one to answer the user; the piggyback kit makes that same call also return what is worth remembering. No extra AI call, no extra bill.

How it works

1. Fetch the kit once: GET /v1/piggyback.
2. Add instructions to your system prompt, with today's date, and ask for reply_schema (or register tool).
3. Show the user reply.
4. Send memories and preferences from the model's output, as they are, to POST /v1/memories with the user_id.

// the model's reply, structured by reply_schema
{"reply": "Got it, I'll keep the biryani vegetarian for Priya.",
 "memories": ["Priya is the user's wife."],
 "preferences": [{"who": "wife", "topic": "diet", "value": "vegetarian", "type": "must", "until": ""}]}

Works with any model that supports structured output or tools, including models on your own servers. Check the results with your model before going live: smaller models may miss or mislabel preferences.

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 counts.

Instances do not sync writes with each other. Each LongMemory instance is one process and one SQLite data file, and it is the only writer of that file. There is no built-in replication, no consensus protocol (no Raft) and no shared state between instances. Durability across zones comes from streaming that file's changes to object storage; scale comes from giving each instance its own share of tenants or users.

Never point two instances at the same data file, and do not keep it on a network file system shared between machines (EFS, NFS, SMB): SQLite's WAL mode relies on shared memory on one machine, so locks are not reliable across hosts and the file can be corrupted. Use a local or block volume (EBS, a persistent disk, a local SSD).

Measured: 1 to 96 share-nothing instances on one AWS c5.24xlarge (96 vCPUs), each sent 1,000 searches at the same instant: throughput rose from 249 to 5,248 searches per second, with all 96,000 answered and 0 errors at 96 instances. Run log

Search cost follows the size of one user's data, not the whole database. Logs and scripts: AWS run · 1M tokens · search times

Full control over structured preferences: a batch of operations applied atomically (all or nothing, up to 200). Use it when you need more than the short form of the save call: people with aliases, merging two people, context such as time of day or place, exact validity windows, or confidence.

{
  "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":"2027-01-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).

The emit_memory_ops tool

GET /v1/schema/ops returns the JSON Schema of an emit_memory_opstool that emits these full operations. Register it on your agent's AI call and send its output here. For most apps the piggyback kit is simpler: it uses the short form and also captures memories.

Preferences only: everything known about the people named, valid now (or at at), matching the moment's context, ranked, plus a rendered context block. No AI, about 0.8 ms. POST /v1/search already includes these preferences; use recall when you want them alone, for named people or domains.

{
  "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 events on their own, up to 500 per batch (the save call takes the same events, up to 100). Recognized payload fields become behaviour signals; three observations of the same pattern within 90 days become an inferred preference, scoped to a time of day when at least 80% of them agree. No AI involved. Search events alone with POST /v1/events/search.

{
  "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.

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.

The one call that uses an AI model, and only if you configure it: text in, preference operations out, using your 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. The piggyback kit is the recommended way and needs no extra AI call.