Memory API Reference

Agent memory integration layer with auto-injection. Provides a MemoryProvider protocol and adapters for external memory backends (Mem0, ChromaDB) plus a lightweight InMemoryProvider for testing. The key feature is auto-injection: MemoryAgent wraps any LangGraph agent and transparently prepends relevant memories to every invocation.

MemoryResult

promptise.memory.MemoryResult dataclass

A single memory search result.

Attributes:

Name	Type	Description
content	str	The stored text.
score	float	Relevance score (0.0 = no match, 1.0 = perfect). Clamped to [0.0, 1.0] on construction.
memory_id	str	Unique identifier for this memory entry.
metadata	dict[str, Any]	Provider-specific metadata.

MemoryProvider

promptise.memory.MemoryProvider

Bases: Protocol

Interface for memory backends.

All methods are async. Implementations must handle their own thread-safety and connection management. Callers should call :meth:close when the provider is no longer needed.

add(content, *, metadata=None) async

Store a new memory.

Parameters:

Name	Type	Description	Default
content	str	Text to remember.	required
metadata	dict[str, Any] | None	Optional metadata (e.g. source, tags).	None

Returns:

Type	Description
str	The memory_id of the stored entry.

close() async

Release resources (connections, file handles).

delete(memory_id) async

Delete a memory by ID.

Returns:

Type	Description
bool	True if the entry existed and was deleted.

search(query, *, limit=5) async

Search for memories relevant to query.

Parameters:

Name	Type	Description	Default
query	str	Natural-language search query.	required
limit	int	Maximum results to return.	5

Returns:

Type	Description
list[MemoryResult]	Ranked list of :class:MemoryResult (best match first).

InMemoryProvider

promptise.memory.InMemoryProvider

Substring-search memory provider for testing.

Stores entries in a dictionary. Search uses case-insensitive substring matching — not suitable for production.

Parameters:

Name	Type	Description	Default
max_entries	int	Maximum stored entries. When exceeded, oldest entries are evicted (FIFO).	10000

ChromaProvider

promptise.memory.ChromaProvider

Adapter for ChromaDB <https://www.trychroma.com/>_.

Requires pip install chromadb (or pip install "promptise[all]"). Provides local vector similarity search with automatic embedding generation. ChromaDB handles its own input validation internally.

Parameters:

Name	Type	Description	Default
collection_name	str	Name of the ChromaDB collection.	'agent_memory'
persist_directory	str | None	Path for persistent storage. When None, uses an ephemeral in-memory client.	None
embedding_function	Any	Custom ChromaDB embedding function. When None, uses ChromaDB's default (all-MiniLM-L6-v2 via Sentence Transformers).	None

Raises:

Type	Description
ImportError	If chromadb is not installed.

Example::

provider = ChromaProvider(
    collection_name="agent_memory",
    persist_directory=".promptise/chroma",
)
await provider.add("User prefers dark mode")
results = await provider.search("theme preferences")

close() async

Release ChromaDB client resources.

After calling close(), any further operations will raise RuntimeError. ChromaDB's PersistentClient does not expose an explicit close method, so we null references to allow garbage collection.

Mem0Provider

promptise.memory.Mem0Provider

Adapter for mem0 <https://github.com/mem0ai/mem0>_.

Requires pip install mem0ai (or pip install "promptise[all]"). Wraps Mem0's hybrid retrieval (vector + optional graph search) behind the :class:MemoryProvider protocol.

Mem0 can run fully local (with Ollama) or via their cloud platform. Pass a config dict to from_config() for self-hosted setups.

Parameters:

Name	Type	Description	Default
user_id	str	Scopes memories to a user (required by Mem0).	'default'
agent_id	str | None	Optional agent identifier for multi-agent scoping.	None
config	dict[str, Any] | None	Optional Mem0 configuration dict. Passed directly to mem0.Memory.from_config(). If None, uses Mem0 defaults.	None

Raises:

Type	Description
ImportError	If mem0ai is not installed.

Example::

provider = Mem0Provider(user_id="user-42")
await provider.add("User prefers dark mode")
results = await provider.search("theme preferences")

close() async

Release Mem0 client resources.

After calling close(), any further operations will raise RuntimeError.

MemoryAgent

promptise.memory.MemoryAgent

Wraps an agent with automatic memory context injection.

Before every :meth:ainvoke, searches the memory provider for content relevant to the user's query and injects matching results as a SystemMessage. The agent sees relevant context without needing explicit memory tools.

If the memory provider fails (timeout, connection error), the agent continues normally without memory context — memory never blocks execution.

Composable with :class:PromptiseAgent::

MemoryAgent(PromptiseAgent(graph), provider)

Parameters:

Name	Type	Description	Default
inner	Any	The wrapped LangGraph agent (Runnable).	required
provider	MemoryProvider	A :class:MemoryProvider implementation.	required
max_memories	int	Maximum results to inject per invocation.	5
min_score	float	Minimum relevance score threshold (0.0--1.0).	0.0
timeout	float	Maximum seconds to wait for memory search.	5.0
auto_store	bool	If True, automatically store each exchange (user input + agent output) after invocation completes.	False

ainvoke(input, config=None, **kwargs) async

Invoke the agent with auto-injected memory context.

astream(input, config=None, **kwargs) async

Stream the agent with auto-injected memory context.

invoke(input, config=None, **kwargs)

Synchronous invoke with memory injection.

sanitize_memory_content

promptise.memory.sanitize_memory_content(content)

Sanitize memory content before injection into agent messages.

Strips known prompt-injection patterns and fence markers so that recalled memory cannot hijack the agent's instruction context. Content is also truncated to a safe injection length.

Uses case-insensitive regex matching with whitespace tolerance to catch pattern variations like "SyStEm :" or "SYSTEM:".

Note

This only affects the injected representation — the stored content in the memory provider remains unmodified.

Parameters:

Name	Type	Description	Default
content	str	Raw memory content string.	required

Returns:

Type	Description
str	Sanitized content safe for injection into a prompt.