ILabMemory
ILabMemory is the only public entry point of the library. Every method you'd call lives on this class. Internally it composes session lifecycle, search, upsert, and storage — but those modules are not part of the public API.
Hexagonal contract: ILabMemory is the sole consumer of the Store ABC. Don't import SQLiteStore directly — use from_path.
Constructor
ILabMemory(store: Store, config: Config | None = None)
Inject a custom Store implementation. Use this only when you need a non-SQLite backend or want to control store creation explicitly. For 99% of cases, use from_path below.
Parameters
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
store | Store | sí | Hexagonal persistence port. Must implement the Store ABC from ilab_memory.core.store. The orchestrator is the only module allowed to call this. |
config | Config | None | no (default None) | Library configuration. Defaults to Config(db_path=":memory:") (sentinel value — db_path is unused when the store is injected directly). |
from_path
ILabMemory.from_path(db_path: str | Path, config: Config | None = None) -> ILabMemory
Recommended factory. Creates an ILabMemory backed by a SQLite database at db_path. Use :memory: for tests and ephemeral runs.
Parameters
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
db_path | str | Path | sí | Filesystem path to the SQLite database (or ":memory:"). Created on first use; idempotent. |
config | Config | None | no (default None) | Optional Config. If provided, its db_path is overridden by the db_path argument so the config always matches the actual store path. |
Returns
A ready-to-use ILabMemory instance.
Context manager
ILabMemory implements __enter__ / __exit__, so you can use it inside a with block to guarantee the underlying store is closed cleanly.
from ilab_memory import ILabMemory
with ILabMemory.from_path("./memory.db") as mem:
mem.mem_session_start("alice")
# ... your work ...
# store is closed automatically here
You can also call mem.close() explicitly. The method is idempotent.
Examples
- Quick start
- In-memory (tests)
- With explicit Config
- Custom Store (advanced)
from ilab_memory import ILabMemory
mem = ILabMemory.from_path("./memory.db")
response = mem.mem_session_start(user_id="alice")
print(response.session_id, response.is_new)
mem = ILabMemory.from_path(":memory:")
# perfect for unit tests — no disk I/O, fresh state each time
from ilab_memory import ILabMemory
from ilab_memory.core.models import Config
cfg = Config(
db_path="./memory.db",
session_timeout_hours=12,
observation_types=("decision", "discovery", "pattern"),
)
mem = ILabMemory.from_path("./memory.db", config=cfg)
from ilab_memory import ILabMemory
from my_app.stores import RedisStore # hypothetical custom backend
store = RedisStore(url="redis://localhost:6379")
mem = ILabMemory(store)
Thread safety
Single-threaded only in v0.1. The default SQLiteStore uses one connection; the caller owns concurrency. If you need multi-thread access, wrap calls in your own lock or upgrade to a custom Store that handles isolation.