Skip to main content

Quickstart

This guide shows the embedded Python flow: install the library, create a store, save an observation (with private content stripping), search it, and close the session with a summary.

1. Install​

iLAB Memory is a single Python package. The core has zero external runtime dependencies beyond Pydantic and the Python standard library (SQLite ships with Python).

pip install ilab-memory

2. Create a memory store​

ILabMemory.from_path is the factory for the SQLite-backed store. Point it at a file path on disk (or :memory: for tests).

from ilab_memory import ILabMemory

mem = ILabMemory.from_path("./memory.db")
tip

ILabMemory is a context manager — use with ILabMemory.from_path(...) as mem: if you want the store to close cleanly at the end of a script.

3. Start a session for a user​

Sessions are per-user and reused if still active (default timeout: configurable in Config). The response carries the session_id, whether it is new, and any prior memory context.

response = mem.mem_session_start(user_id="alice")

print(response.session_id)        # e.g. 1
print(response.is_new)            # True on first call for this user
print(len(response.memories))     # prior observations scored with ContextScore

4. Save an observation​

mem_save requires user_id, content, type, and title. Pass topic_key when the same topic may be updated across turns — subsequent saves with the same key upsert in place instead of duplicating.

Anything inside <private>...</private> is stripped before the content is hashed or persisted. Secrets never reach disk.

result = mem.mem_save(
    user_id="alice",
    type="preference",
    title="Preferred greeting",
    content="Alice prefers being greeted as 'Ali'. <private>API key: sk-xxx</private>",
    topic_key="user/alice/greeting",
)

print(result.id)        # observation id
print(result.outcome)   # 'created' | 'updated' | 'deduped'

5. Search memory​

mem_search runs full-text search (FTS5) scoped to the user, returning compact observations ranked by SearchScore (combining FTS rank, recency, and revision signals).

results = mem.mem_search(
    user_id="alice",
    query="greeting",
    limit=5,
)

for obs in results:
    print(obs.id, obs.score, obs.title)
note

Results come back as ObservationCompact (small payload, ~100 tokens). Use mem_get_observation to load the full content when you need it.

6. Get the full observation​

Compact results omit content for brevity. Hydrate the full record by id when you need to inspect or render it. Notice that the <private> block is gone — only [REDACTED] remains.

obs = mem.mem_get_observation(user_id="alice", observation_id=result.id)

print(obs.content)
# → "Alice prefers being greeted as 'Ali'. [REDACTED]"

7. Close the session with a summary​

When the conversation ends, write a human-readable summary so the next session can pick up where this one left off.

closed = mem.mem_session_end(
    user_id="alice",
    summary="Captured Alice's preferred greeting and confirmed the agent will use 'Ali'.",
)

print(closed.id, closed.completed_at)
tip

Want the same flow over the network? iLAB Memory ships an HTTP REST server (FastAPI) and an MCP stdio server — both expose the exact same operations and serialize the same Pydantic models. See the API Reference once Fase 4 lands.

What's next?​

Concepts

Sessions, observations, topic_keys, scoring, privacy, and the Braess points behind the design.

Cookbook

End-to-end recipes — embedding iLAB Memory into a FastAPI chat, a Tauri assistant, an autonomous agent.

API Reference

Full Pydantic schemas, the ILabMemory facade, the HTTP OpenAPI spec, and the MCP tool list.