Skip to content

MemoryStore API

cmm.core.memory_store.MemoryStore

Content-addressable memory store using FAISS for similarity search. Uses FAISS IVF (Inverted File Index) for O(1) amortized lookup. Buffers initial writes until enough data exists to train the IVF index, falling back to flat (exact) search during the buffer phase.

Constructor

from cmm.core.memory_store import MemoryStore

store = MemoryStore(
    dim=384,          # Embedding dimension (768 for all-mpnet-base-v2)
    nlist=100,        # Number of IVF cells
    nprobe=8,         # Number of cells to probe during search
    use_gpu=False,    # Use GPU-accelerated FAISS
)

The training threshold for IVF is max(nlist * 10, 256). Until that many vectors are stored, exact flat search is used.

Methods

store

memory = store.store(
    gist: Gist,
    embedding: np.ndarray,
    memory_type: MemoryType = MemoryType.EPISODIC,
    importance: float = 1.0,
    source_role: Role | None = None,
    timestamp: float | None = None,
    agent_id: str | None = None,
    session_id: str | None = None,
    scope: MemoryScope = MemoryScope.TEAM,
) -> Memory

Store a memory and return it. The embedding is L2-normalized internally. Automatically triggers IVF training when enough vectors have been added.

retrieve

results = store.retrieve(
    query_embedding: np.ndarray,
    top_k: int = 5,
    threshold: float = 0.0,
    agent_id: str | None = None,
) -> list[RetrievalResult]

Retrieve memories by similarity. Returns raw results without decay or priming adjustments.

If agent_id is provided, scope filtering is applied:

  • TEAM and SHARED scope: visible to all agents
  • PRIVATE scope: visible only to the creating agent

get

memory = store.get(memory_id: int) -> Memory | None

Get a single memory by ID. Returns None if not found.

update_access

store.update_access(memory_id: int) -> None

Record that a memory was accessed. Increments access_count and updates last_accessed timestamp. Used by the decay scorer and rehearsal tracking.

remove

success = store.remove(memory_id: int) -> bool

Mark a memory as removed. Requires rebuild_index() to take effect in FAISS. Returns True if the memory existed.

rebuild_index

store.rebuild_index() -> None

Rebuild the FAISS index from remaining memories. Call this after removing memories to sync the FAISS index. Re-trains IVF if enough vectors remain.

clear

store.clear() -> None

Remove all memories and reset the index.

save

store.save(directory: str) -> None

Save to disk. Creates:

  • faiss.index -- FAISS binary index
  • memories.json -- all memory metadata and ID mappings

load (classmethod)

store = MemoryStore.load(directory: str) -> MemoryStore

Load a memory store from disk. Restores the FAISS index and all memory metadata.

Properties

Property Type Description
size int Number of memories stored
is_trained bool Whether the IVF index has been trained
dim int Embedding dimension

Thread Safety

All store and retrieve operations are protected by a threading lock. The store is safe to use from multiple threads concurrently.