Start with one memory.

00 / See the whole loop in 30 seconds.

Before wiring anything, run the built-in demo. It creates a temporary store, writes facts with validity windows and recalls them at two points in time, runs 1,000 simulated support tickets through a randomized holdout, audits the experiment, and lets the evidence withdraw a harmful memory and graduate a helpful one.

The agent and its outcomes are simulated with planted effects, so the measured effects can be checked against ground truth. The store, randomization, integrity audit, analysis and withdrawal are the real product. It needs no LLM, no API key and no network.

unimem demo --json          # inspect the structured result

01 / Recall your first fact.

After installing the local core above, add one fact to a fresh store. The base core uses PyYAML and does not require an LLM or an embedding service.

Run these commands from your terminal. The final command asks the local store for the fact you just added. This proves the persistence and recall path; it does not yet establish that memory improves a task.

unimem init --dest ./mem
unimem fact add "The launch checklist is stored in the blue folder." --dest ./mem
unimem recall "Where is the launch checklist stored?" --dest ./mem

02 / Give the memory loop an outcome.

Configure a trial before running the Python example. Here, a small retrieval function stands in for your own retriever. Each returned memory has a stable ID and text. The task-1042 occasion ID must identify one actual task.

Only pass the returned shown list into your agent. Report the final result using a real success criterion, including failures and escalations. One task will not produce a meaningful effect estimate.

unimem experiment --configure --rate 0.5 --dest ./mem

03 / Wrap a retrieval callable.

Save this as example.py in the product checkout. The printed result may be empty because the one memory can be withheld. Replace the illustrative outcome with the result of your workflow before using this for a real experiment.

from unimem.measure import CausalMemory

def retrieve(task):
    return [{"id": "retry-429",
             "text": "On HTTP 429, back off and retry."}]

memory = CausalMemory(retrieve, root="./mem")
shown = memory.recall("Handle a rate limit",
                      occasion_id="task-1042")
print(shown)
# Run the actual agent here with only shown memories.
# Illustrative label: replace with the actual final outcome.
memory.record_outcome("task-1042", succeeded=True)

04 / Connect a coding agent or MCP client.

Install the optional serve dependency for MCP. A stdio client launches the process locally; it operates with that process’s OS permissions. Network transports and the multi-tenant Hub have different authentication boundaries.

The installer contains targets for Claude Code, Cursor, Windsurf, Codex, Copilot, Gemini, Devin, OpenCode, and generic MCP configuration. The installer writes configuration; provider behavior still needs validation in your environment.

python -m pip install -e '.[serve]'
unimem serve --transport stdio --dest ./mem

# Or generate a supported coding-agent configuration:
unimem install --target codex

05 / Use HTTP from your own runtime.

Run unimem up --dest ./mem and use the private gateway bearer token provided at startup. The local gateway defaults to port 8787. Keep the token on the server or in your local environment.

The recall endpoint accepts candidate items and an occasion ID. Deliver only the returned memory set, then send the final outcome to /v1/outcome. Consult the OpenAPI contract for response fields, protected items, limits, and policy errors.

curl http://localhost:8787/v1/outcome \
  -H "Authorization: Bearer $UNIMEM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"occasion_id":"task-1042","succeeded":true}'