aimu.memory

Semantic facts, path-based documents, and a shared abstract base.

aimu.memory.MemoryStore

Bases: ABC

Abstract interface for memory store implementations.

All implementations must support storing, searching, deleting, and listing content. Concrete subclasses add implementation-specific methods on top of this baseline.

store abstractmethod

store(content: str) -> None

Store a string in the memory store.

search abstractmethod

search(query: str, n_results: int = 10) -> list[str]

Return up to n_results strings relevant to query.

delete abstractmethod

delete(identifier: str) -> None

Remove content by identifier (path, exact string, or UUID).

list_all abstractmethod

list_all() -> list[str]

Return all stored identifiers or content strings.

aimu.memory.SemanticMemoryStore

SemanticMemoryStore(collection_name: str = 'memories', persist_path: Optional[str] = None)

Bases: MemoryStore

Persistent store for factual memories backed by ChromaDB.

Memories are natural-language strings in subject-predicate-object form, e.g. "Paul works at Google" or "Sarah is the sister of Emma". ChromaDB embeds each fact so that topic-based retrieval ("work", "family life") finds semantically relevant facts without exact-string matching.

Parameters:

Name	Type	Description	Default
collection_name	str	ChromaDB collection name (default: "memories").	'memories'
persist_path	Optional[str]	Directory path for persistent storage. If None, uses an in-memory ephemeral client.	None

Examples:

>>> store = SemanticMemoryStore()
>>> store.store("Paul works at Google")
>>> store.store("Paul is married to Sarah")
>>> store.store("Sarah is the sister of Emma")
>>> store.search("work")        # ["Paul works at Google"]
>>> store.search("family life") # marriage / sibling facts

store

store(content: str) -> None

Store a fact string in the memory store.

The fact should be a natural-language sentence in subject-predicate-object form, e.g. "Paul works at Google" or "Sarah is the sister of Emma".

Parameters:

Name	Type	Description	Default
content	str	The fact string to store.	required

search

search(query: str, n_results: int = 10, max_distance: float | None = None) -> list[str]

Retrieve facts semantically related to a query.

Uses ChromaDB's vector similarity search so broad topics like "work" or "family life" match relevant facts without exact-string matching.

Parameters:

Name	Type	Description	Default
query	str	Natural-language query (e.g. "work", "family").	required
n_results	int	Maximum number of facts to return.	10
max_distance	float | None	Optional cosine-distance cutoff (0 = identical, 2 = maximally dissimilar). Facts with a distance above this threshold are excluded. Typical useful range: 0.3 (tight) – 0.6 (loose). Defaults to None (no cutoff).	None

Returns:

Type	Description
list[str]	List of fact strings ordered by relevance.

delete

delete(identifier: str) -> None

Remove all stored facts that exactly match the given string.

Parameters:

Name	Type	Description	Default
identifier	str	The exact fact string to remove.	required

list_all

list_all() -> list[str]

Return all stored fact strings.

aimu.memory.DocumentStore

DocumentStore(persist_path: Optional[str] = None)

Bases: MemoryStore

Path-addressed document store backed by the filesystem or an in-memory dict.

Implements the :class:MemoryStore abstract interface so it can be swapped with :class:SemanticMemoryStore in any application, and adds the richer path-based API that mirrors Anthropic's Managed Agents Memory tools.

Parameters:

Name	Type	Description	Default
persist_path	Optional[str]	Root directory for persistent storage. If None the store is ephemeral (in-memory only).	None

Examples:

>>> store = DocumentStore()
>>> store.write("/preferences.md", "Use concise responses.")
>>> store.read("/preferences.md")
'Use concise responses.'
>>> store.edit("/preferences.md", "concise", "detailed")
>>> store.search_full_text("detailed")
[{"path": "/preferences.md", "content": "Use detailed responses."}]

write

write(path: str, content: str) -> None

Create or overwrite a document at path.

Parameters:

Name	Type	Description	Default
path	str	Memory path, e.g. "/preferences.md".	required
content	str	Text content to store (≤ 100 KB recommended).	required

read

read(path: str) -> str

Return the content of the document at path.

Raises:

Type	Description
KeyError	If no document exists at path.

edit

edit(path: str, old_str: str, new_str: str) -> None

Replace the first occurrence of old_str with new_str in the document at path.

Parameters:

Name	Type	Description	Default
path	str	Memory path of the document to edit.	required
old_str	str	Exact substring to find.	required
new_str	str	Replacement text.	required

Raises:

Type	Description
KeyError	If no document exists at path.
ValueError	If old_str is not found in the document.

list_paths

list_paths(prefix: Optional[str] = None) -> list[str]

Return all memory paths, optionally filtered by prefix.

Parameters:

Name	Type	Description	Default
prefix	Optional[str]	Only return paths that start with this string. Pass None (default) to return all paths.	None

Returns:

Type	Description
list[str]	Sorted list of path strings.

search_full_text

search_full_text(query: str, n_results: int = 10) -> list[dict]

Case-insensitive substring search across all document contents.

Parameters:

Name	Type	Description	Default
query	str	Search string.	required
n_results	int	Maximum number of results to return.	10

Returns:

Type	Description
list[dict]	List of {"path": ..., "content": ...} dicts for matching
list[dict]	documents, ordered by path.

store

store(content: str) -> None

Store content at an auto-assigned path (/note-{uuid}.md).

Use :meth:write directly when you need control over the path.

Parameters:

Name	Type	Description	Default
content	str	Text content to store.	required

search

search(query: str, n_results: int = 10) -> list[str]

Full-text search; returns a list of matching content strings.

Parameters:

Name	Type	Description	Default
query	str	Search string.	required
n_results	int	Maximum number of results.	10

Returns:

Type	Description
list[str]	List of content strings from matching documents.

delete

delete(identifier: str) -> None

Delete the document at identifier (treated as a memory path).

No-op if the path does not exist.

Parameters:

Name	Type	Description	Default
identifier	str	Memory path of the document to remove.	required

list_all

list_all() -> list[str]

Return all memory paths (sorted).