Quickstart

Get from install to first recall in under a minute.

1. Install

Not on PyPI — install directly from GitHub:

pip install git+https://github.com/CodebyKumar/elastimem.git

No required dependencies — this works standalone.

2. Open a store

import elastimem

mem = elastimem.open("~/.myagent/memory.db")

That's the whole setup. elastimem.open(path, **kwargs) creates the SQLite file if it doesn't exist, and every capability beyond "remember facts, recall past turns" is optional — see below.

3. Remember something

mem.remember("name", "Priya")
mem.remember("favorite_color", "teal")

print(mem.facts())
# {'name': 'Priya', 'favorite_color': 'teal'}

4. Record a conversation turn

mem.record_turn(
    "what's the capital of Japan?",
    "Tokyo is the capital of Japan.",
)

record_turn persists the exchange and runs free regex-based fact capture (names, locations) inline — no LLM required.

5. Recall

hits = mem.recall("capital of Japan")
for h in hits:
    print(h.kind, h.text[:80])

recall() never raises — a failed or degraded search just returns fewer results, never an exception that could break your chat loop.

6. Wire it into a chat loop

The pattern every example in examples/ follows:

while True:
    user_input = get_user_input()

    plan = mem.build_context(user_input)   # budgeted prompt sections
    prompt = plan.render() + f"\nUser: {user_input}\nAssistant:"
    reply = my_llm(prompt)                  # your model call, any backend

    mem.record_turn(user_input, reply)

build_context() assembles facts, relevant past moments, session summaries, and lessons into a token budget that's automatically sized to the machine Elastimem is running on (see governor.md) — you don't have to think about how much context is "too much" for a small model on constrained hardware.

7. End the session

mem.end_session()   # summarizes, consolidates, closes the session
mem.close()          # stop background worker, close DB connections

Adding an LLM and embedder

Everything above works with zero external dependencies. Pass an LLM and/or embedder to unlock automatic fact extraction and semantic (vector) recall — both are plain callables, so any backend works:

mem = elastimem.open(
    "~/.myagent/memory.db",
    llm=my_complete_fn,       # (prompt, *, max_tokens, temperature) -> str
    embedder=my_embed_fn,     # (list[str]) -> list[list[float]]
    context_tokens=4096,      # match your model's context window
)

If you don't pass an embedder, Elastimem activates its own small built-in one automatically (see governor.md) — semantic recall works out of the box, no setup required.

The knowledge graph (with an LLM configured)

With llm= set, record_turn also extracts entities and relationships in the same background pass that captures facts — no extra model call, no NER library. They connect memories that share no vocabulary:

mem.record_turn("I'm building a robot called Tuffy that runs on a Jetson",
                 "Sounds like a fun project!")
mem.end_session()   # graph maintenance runs here: decay, dedup, clustering

hits = mem.recall("what do I know about my Jetson")   # finds the Tuffy turn too

for cluster in mem.clusters():        # entities auto-grouped into topics
    print(cluster["label"], cluster["members"])

This is one more retrieval signal, not a separate database — 1-hop at LITE and STANDARD, 2-hop at FULL. See governor.md for the full design, and api.md for explain()/timeline(), the two Experimental query methods built on top of it.

Where to go next

installation.md — optional extras, supported Python versions
architecture.md — how the pieces fit together
governor.md — how token budgets and degradation work
api.md — every public method, in detail
api_stability.md — what's safe to depend on long-term
examples/ — runnable scripts: no-LLM, llama.cpp, OpenAI-compatible API, memory-only usage

FilesExpand file tree

quickstart.md

Latest commit

History