Episode log and rebuildable facts
Episodes are kept as an append-only log, while facts provide a rebuildable projection. Calling `rebuild()` can replay the same episodes through an updated extraction pipeline.
TenseMem
TenseMem is an embedded Python memory system for AI agents that maintains current and historical typed facts in a SQLite-backed store. It uses model-proposed operations with deterministic resolution, freshness-aware reads, and persistent corrections.
Embedded, time-aware memory for AI agents
TenseMem is an embedded Python memory system for AI agents that need more than similarity-based recall. It stores episodes and derives typed facts from them, maintaining current state alongside historical values so an agent can distinguish what is true now from what was true earlier.
The default store is a single SQLite file used within the application process, with no separate server required for the core workflow. An extractor proposes operations from user messages, while deterministic rules resolve and apply those operations. Reads such as `state()`, `history()`, `context()`, and `search()` expose freshness information so applications can tell whether returned memory reflects the latest input.
Key features
Temporal cardinality
ONE predicates maintain at most one active value, superseding older values without deleting their history. MANY predicates support multiple active values until they are replaced or removed.
Freshness-aware reads
State, history, context, and search reads report the episode watermark, pending work, and failure status. `context()` can wait for a requested sequence before returning.
Contamination controls
Recalled `context()` text is fenced and fenced spans are removed before extraction. Proposed operations also require a verbatim quote from the remaining user text, helping prevent self-echo.
Persistent corrections
`correct(fact_id)` marks a fact as never true, restores the value it displaced, and preserves the correction across rebuilds while allowing later genuine changes.
Practical use cases
User profile state
Track facts such as a user's current city while retaining superseded values for questions about previous locations. The state model avoids forcing the agent to choose between current and historical matches returned by similarity search.
Fresh conversational context
Use freshness watermarks and pending-message information when an agent needs to know whether a response is based on the latest user message. A caller can wait for a minimum episode sequence before reading context.
Reliable correction workflows
Represent corrections to remembered facts with `correct(fact_id)`, restoring the displaced value and keeping the correction during a later rebuild. This supports workflows where an agent must recover from an incorrectly extracted claim.
Local agent development
Run the memory engine locally through its Python API, CLI, REST service, MCP interface, or local Studio inspector. This suits developers testing agent memory on a single SQLite database before connecting a real extractor.
Pros and Cons
Pros
- Embedded operation uses one SQLite file and does not require a separate memory service.
- Deterministic resolution separates model-proposed operations from state mutations.
- Current values, historical facts, freshness status, and corrections are represented explicitly.
- The core test workflow can run without API keys or hosted model calls.
Cons
- The project is identified as version 0.1.0 alpha, so APIs and behavior may still change.
- The documented default storage is SQLite; a second SQL dialect and hosted multi-tenant Studio are not shipped in the repository.
- Real-model extraction requires configuring a supported provider and its credentials; the no-key FakeExtractor is rule-based.
FAQ
How do you get started with TenseMem?
TenseMem is a Python package. A minimal setup creates a Memory instance with an extractor, registers a predicate such as `lives_in`, adds a user message, and reads the resulting context. `FakeExtractor` can be used without an API key; provider extras are available for OpenAI, Anthropic, Ollama, LiteLLM, and Gemini workflows.
Does the language model directly control memory changes?
The extractor proposes typed operations from episodes, but deterministic resolver rules decide which mutations are allowed and apply them to the SQLite-backed state. The model does not directly decide the final state.
How does TenseMem handle changing or multiple values?
Yes. Predicates can be cardinality ONE or MANY. With a ONE predicate, a newer value supersedes the previous active value while the earlier fact remains available through history. A MANY predicate can retain several active values until values are replaced or removed.
What happens when extraction is still processing?
Reads expose freshness information, including the episode sequence reflected, pending messages, and whether processing has failed. `context()` can wait for a minimum sequence, while still exposing whether the returned state is current if extraction has not completed.
Quick Facts
- Category
- Developer Tool
- Primary users
- AI agent developers
- Platform
- Python package
- Default storage
- SQLite file
- Status
- 0.1.0 alpha
- Interfaces
- Python API, CLI, REST, MCP, and local Studio