Memory that knows its tenses. Embedded, deterministic memory that AI agents can safely act on.

One SQLite file. No server required. The model proposes typed facts; the engine decides what is current.

pip install tensemem

from tensemem import FakeExtractor, Memory

mem = Memory(llm=FakeExtractor()) mem.register_predicate("lives_in") added = mem.add("u1", "I live in Delhi") ctx = mem.context(user_id="u1", min_seq=added.seq, wait=1.5) print(ctx.text) # fenced block the model can read print(ctx.freshness.is_current) # True once extract finished

FakeExtractor is rule-based and needs no API key. Same API with tensemem[openai], tensemem[anthropic], tensemem[ollama], tensemem[litellm], or Gemini (GEMINI_API_KEY in the process environment).

Similarity search returns both “I live in Delhi” and “I moved to Bangalore” and leaves the model to guess. TenseMem keeps one current value per slot, says whether the read is fresh, and refuses to learn from its own output.

mem.add("u1", "I live in Delhi") mem.set(user_id="u1", predicate="lives_in", value="Bangalore")

print(mem.state("u1").values)

{"lives_in": "Bangalore"}

history = mem.history("u1", predicate="lives_in")

ACTIVE Bangalore, SUPERSEDED Delhi

bangalore = next(f for f in history.facts if f.object == "Bangalore") mem.correct(bangalore.id) # that move was never true print(mem.state("u1").values)

{"lives_in": "Delhi"}

flowchart LR E[episodes] --> X[extractor proposes ops] X --> R[resolver] R --> F[facts] F --> C["context() + freshness"] C -.->|fence stripped| X

Loading

Architecture

Every surface is an adapter over Memory / AsyncMemory. The model proposes typed ops; resolve() decides mutations; apply() writes one SQLite file. Facts are a rebuildable projection of an append-only episode log.

Editable source: docs/architecture.excalidraw. File map: Architecture.

Do not auto-register unknown predicates, skip keep_ops, or teach the engine from fenced context() text. Those are locked by tests.

tensemem bench scores the packaged 101 conversations with FakeExtractor (no network):

Reproduce with tensemem bench. Methodology: TenseBench.

tensemem inspect --user u1 tensemem history --user u1 lives_in tensemem search --user u1 "where did I live"

TenseMem Studio is a local Next.js inspector over tensemem serve (board, memories table, playground, compare, echo). It is not a chatbot. Secrets stay in the serve process environment — never in the Token field. Studio lives in the git checkout, not on PyPI.

git clone https://github.com/tensemem/tensemem.git cd tensemem pip install "tensemem[server]"

Terminal 1 — HTTP:

tensemem --db ./studio.db serve --port 8080

Terminal 2 — Studio:

cd studio && npm install && npm run dev

Extras

Extra What you get

tensemem[openai] / [anthropic] / [ollama] / [litellm] Hosted or local extract

tensemem[server] tensemem serve REST + Studio backend

tensemem[mcp] stdio or tensemem mcp --http

tensemem[langgraph] TenseMemStore (put / search)

tensemem[llamaindex] TenseMemChatMemory (put / get)

tensemem[local] FastEmbed vectors for search

Gemini extract uses GEMINI_API_KEY (or GOOGLE_API_KEY) in the environment of the process that runs extract. No extra package beyond the server if you use the built-in Gemini adapter.

--token / TENSEMEM_TOKEN is optional bearer auth on HTTP. Bind stays loopback unless you put a TLS proxy in front.

0.1.0 alpha. The Python API, CLI, REST, MCP, and Studio are usable on a single SQLite file. The default store is SQLite; a second SQL dialect is not shipped. Multi-tenant hosted Studio is not in this tree.

Quickstart · Concepts · Architecture · API · CLI · REST · Studio · MCP · Operations · ADRs

uvx mkdocs serve previews the same pages locally.

Default tests need no API keys and never call a model. From a git checkout:

git clone https://github.com/tensemem/tensemem.git cd tensemem uv sync uv run ruff check . uv run ruff format --check . uv run pyright uv run pytest

Studio (optional, when you change studio/):

cd studio && npm ci && npm run typecheck && npm run build

Live extract against a real model (skipped unless both are set):

uv sync --extra openai TENSEMEM_LIVE=1 OPENAI_API_KEY=… uv run pytest -m live

Environment variables

Model keys belong in the process that runs extract (your script, or the tensemem serve terminal). They are never valid values for Studio Token.

Ollama needs a local Ollama process, not an env key. Details: Studio, REST, SECURITY.md.

See CONTRIBUTING.md. main is protected; every change is a pull request. Merges wait until CI, PR quality, and CodeQL are green.