thread-recall
Part of the Governed Agent Stack: free, on-prem building blocks for an AI agent you can point at a real database and audit.
Governed, on-prem conversation memory for AI agents. It stores what an agent should remember across turns — per-thread history and optional semantic recall — and makes that memory governable: PII can be masked before it is ever written, and every write can be mirrored into a tamper-evident audit log.
The default backend is SQLite with embeddings as JSON and cosine in Python: zero dependencies, works immediately, nothing leaves the building. A Postgres + pgvector backend (for scale) is the next step; the scoring logic is backend-agnostic so it drops in cleanly.
This is the write-side companion to sql-steward. sql-steward is the read-only query gateway and stays read-only; thread-recall is where agent state lives, kept separate on purpose.
Quickstart
pip install thread-recall
thread-recall demo
from thread_recall import Memory
mem = Memory("agent.db") # or ":memory:"; mask=True / audit=True optional
mem.remember("thread-42", "user", "How much MRR did the pro plan make?", embedding=embed(q))
mem.remember("thread-42", "assistant", "Pro plan MRR was 297.")
mem.recent("thread-42", k=10) # last 10 turns, chronological
mem.search("thread-42", embed("revenue"), k=5) # nearest turns by embedding
Why it's "governed"
- PII masked on write.
Memory(..., mask=True)runs content through pii-veil before it is stored, so raw personal data never lands in the memory store. No-op if pii-veil isn't installed. - Tamper-evident audit.
Memory(..., audit=True)mirrors every write into an agent-blackbox hash-chained ledger, so "what did the agent choose to remember" has a checkable answer. No-op if agent-blackbox isn't installed. - On-prem by default. SQLite file on your disk; embeddings generated by whatever local model you choose. Nothing is sent out.
API
| Method | Purpose |
|---|---|
remember(thread_id, role, content, embedding=None, metadata=None) |
Store a turn (PII-masked first if enabled). Returns its id. |
recent(thread_id, k=10) |
Last k turns, chronological. |
search(thread_id, query_embedding, k=5) |
Semantic recall: nearest turns by cosine over stored embeddings. |
forget(thread_id) |
Delete a thread's memory. |
count(thread_id=None) |
Turn count for a thread, or overall. |
Embeddings are supplied by the caller (generate them with any local model). thread-recall stores and scores them; it does not call out to any embedding service itself.
Roadmap
- Postgres + pgvector backend for scale and native nearest-neighbour (the SQLite backend computes cosine in Python, fine for thread-scoped recall, not for millions of rows).
- A thin LangGraph adapter, to use thread-recall alongside a LangGraph checkpointer.
Develop
git clone https://github.com/Pawansingh3889/thread-recall
cd thread-recall
pip install -e ".[dev]"
pytest -q
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file thread_recall-0.1.1.tar.gz.
File metadata
- Download URL: thread_recall-0.1.1.tar.gz
- Upload date:
- Size: 10.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1bd12697600ae4db35612e9ec89e9db4c55321808efc4dead5d758f2d3777b29
|
|
| MD5 |
6dbb305bd0244f9c176f4e519029d48d
|
|
| BLAKE2b-256 |
734c88239646bc1f69e7cecc0e5e8d3c115a22a44631d05d725c69bbecd82cf9
|
Provenance
The following attestation bundles were made for thread_recall-0.1.1.tar.gz:
Publisher:
release.yml on Pawansingh3889/thread-recall
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
thread_recall-0.1.1.tar.gz -
Subject digest:
1bd12697600ae4db35612e9ec89e9db4c55321808efc4dead5d758f2d3777b29 - Sigstore transparency entry: 2195425279
- Sigstore integration time:
-
Permalink:
Pawansingh3889/thread-recall@a9b32f8cd1192d44bdb894ce0e3c61761e89d05e -
Branch / Tag:
refs/tags/v0.1.1 - Owner: https://github.com/Pawansingh3889
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@a9b32f8cd1192d44bdb894ce0e3c61761e89d05e -
Trigger Event:
push
-
Statement type:
File details
Details for the file thread_recall-0.1.1-py3-none-any.whl.
File metadata
- Download URL: thread_recall-0.1.1-py3-none-any.whl
- Upload date:
- Size: 10.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e2fc5d7e6863f20c20d2aa7d69586064a5394c134caf27e02de0af6274adfbb1
|
|
| MD5 |
6a1f5660a1719b64e20217d7b4c7f093
|
|
| BLAKE2b-256 |
e8101eab368462d0532c6b960e9d959e7f870683fa33ee6e91b9b65f3be397ba
|
Provenance
The following attestation bundles were made for thread_recall-0.1.1-py3-none-any.whl:
Publisher:
release.yml on Pawansingh3889/thread-recall
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
thread_recall-0.1.1-py3-none-any.whl -
Subject digest:
e2fc5d7e6863f20c20d2aa7d69586064a5394c134caf27e02de0af6274adfbb1 - Sigstore transparency entry: 2195425310
- Sigstore integration time:
-
Permalink:
Pawansingh3889/thread-recall@a9b32f8cd1192d44bdb894ce0e3c61761e89d05e -
Branch / Tag:
refs/tags/v0.1.1 - Owner: https://github.com/Pawansingh3889
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@a9b32f8cd1192d44bdb894ce0e3c61761e89d05e -
Trigger Event:
push
-
Statement type:
