Loading
Loading
One SQLite file per user, FTS5-indexed. WAL mode. No ~/.atlaso/ global — atlaso writes alongside your project.
<base>/
├── users/
│ └── <sha256(user_id)[:16]>/
│ └── field.db # per-user store
├── _unscoped/
│ └── field.db # atlaso.admin writes
└── _idempotency.db # 24h Stripe-style dedup keysPer-user files give you cheap multi-tenancy without the cross-tenant risk of a shared schema. The hash is a stable 16-character prefix of sha256(user_id); collisions are astronomically unlikely and a collision still lands two users in the same file rather than leaking one into the other.
CREATE TABLE deposits (
id TEXT PRIMARY KEY,
content TEXT NOT NULL,
polarity TEXT NOT NULL CHECK (polarity IN ('positive','negative','cautionary','open')),
evidence_grade TEXT NOT NULL CHECK (evidence_grade IN ('anecdotal','observed','replicated','verified')),
author TEXT NOT NULL,
task_id TEXT,
repro_status TEXT NOT NULL CHECK (repro_status IN ('unreplicated','replicated','failed_repro')),
created_at TEXT NOT NULL,
scope_note TEXT NOT NULL,
scope_model TEXT,
scope_dataset TEXT,
scope_env TEXT,
scope_version TEXT,
scope_n INTEGER,
scope_seed INTEGER,
tags_json TEXT NOT NULL,
artifact_refs_json TEXT NOT NULL,
author_role TEXT
);
CREATE INDEX deposits_created_at ON deposits(created_at);
CREATE INDEX deposits_polarity ON deposits(polarity);
CREATE VIRTUAL TABLE deposits_fts USING fts5(
body,
content='' -- contentless: stores tokenization, not source text
);
-- No ON DELETE CASCADE — hard delete in _local.py removes
-- contradiction edges manually in FK-safe order.
CREATE TABLE contradictions (
from_deposit_id TEXT NOT NULL,
to_deposit_id TEXT NOT NULL,
reason TEXT NOT NULL,
created_at TEXT NOT NULL,
PRIMARY KEY (from_deposit_id, to_deposit_id),
FOREIGN KEY (from_deposit_id) REFERENCES deposits(id),
FOREIGN KEY (to_deposit_id) REFERENCES deposits(id)
);
CREATE TABLE query_log (
id TEXT PRIMARY KEY, -- UUID string
created_at TEXT NOT NULL,
bag_key TEXT,
is_confident INTEGER,
has_conflict INTEGER,
is_single_sample INTEGER,
bag_size INTEGER,
result_count INTEGER
);
-- Additional tables (tasks, messages, consultations) ship with the
-- vendored engine to support the upstream research-lab features. They
-- are not part of the SDK's public surface.deposits_fts uses content='' — a contentless virtual table that stores tokenization but not the source text. The indexed body column is content + tags + scope.note merged at insert time so a single FTS query matches across all three fields.
foreign_keys=ON — supersession edges cascade on hard delete.journal_mode=WAL — concurrent readers and writers.busy_timeout=5000 — five-second wait on lock.Connections are serialised by a threading.RLock at the SDK boundary, so multi-threaded applications are safe without any user-side coordination.
When Memory() is constructed without an explicit path=, storage location is resolved lazily on first call:
path= kwarg.ATLASO_PATH env var..atlaso/ directory wins.pyproject.toml, package.json, .git, Cargo.toml, or go.mod — creates <root>/.atlaso/.<cwd>/.atlaso/.Walk stops at $HOME or filesystem root, depth-capped at 64.
A soft retract adds an atlaso:retracted=... tombstone tag — the deposit becomes invisible to recall() but the row survives. A hard delete removes the row and triggers an FK-safe contentless delete on the FTS index. Default is soft. Use hard_delete=True only for GDPR / PII.
The _engine/ directory is byte-identical-vendored from the upstream monorepo at wheel build time (Hatch hook in tools/vendor_engine.py). A CI gate (tools/verify_engine_parity.py) blocks releases where the SDK's copy has drifted from the source of truth. The SDK never edits engine files in place.
Was this page helpful?