Core Data Structures

MemoryUnit

MemoryUnit is the basic memory record.

Constructor:

MemoryUnit(
    uid: str,
    raw_data: dict[str, Any],
    metadata: dict[str, Any] | None = None,
    embedding: np.ndarray | None = None,
    sparse_embedding: dict[int, float] | np.ndarray | None = None,
)

Important fields:

  • uid is a non-empty string.

  • raw_data is a dictionary. Text extraction prefers text_content, content, description, summary, title and message.

  • text_cached is maintained from raw_data for retrieval and display.

  • embedding stores dense vectors.

  • sparse_embedding stores SPLADE-style sparse vectors.

MemorySpace

MemorySpace is a logical tree container. It stores unit UIDs and child space names, not full unit objects and not local FAISS indexes.

Useful methods:

  • add_unit(unit_or_uid)

  • remove_unit(unit_or_uid)

  • add_child_space(space_or_name)

  • remove_child_space(space_or_name)

  • contains_unit(unit_or_uid, recursive=False)

  • get_unit_uids()

  • get_all_unit_uids(recursive=True)

SemanticMap

SemanticMap owns in-memory units, memory spaces, dense embeddings, optional SPLADE vectors and a global FAISS index.

Constructor:

SemanticMap(
    embedding_model_name="Qwen/Qwen3-Embedding-0.6B",
    embedding_dim=None,
    faiss_index_type="IDMap,Flat",
    use_flash_attention=None,
    **kwargs,
)

Common methods:

  • add_unit(unit, space_names=None, index_update_mode="incremental", generate_sparse_embedding=True)

  • batch_add_units(units, batch_size=32, space_names=None, per_unit_space_names=None)

  • create_memory_space(space_name)

  • add_unit_to_space(unit_or_uid, space_name)

  • get_units_by_spaces(space_names, mode="union", recursive=True)

  • search_similarity_by_text(query_text, k=5, ms_names=None, candidate_uids=None)

  • search_similarity_by_vector(query_embedding, k=5, ms_names=None, candidate_uids=None)

  • get_multi_retriever()

  • save_map(directory_path) and load_map(directory_path) for resident map-only state; use graph snapshots when tiered paging is enabled

SemanticGraph

SemanticGraph wraps a SemanticMap and adds a rustworkx directed graph for explicit relationships and graph traversal.

Constructor:

SemanticGraph(semantic_map_instance: SemanticMap | None = None)

Common methods:

  • add_unit(...) and batch_add_units(...)

  • add_relationship(source_uid, target_uid, relationship_name, bidirectional=False, **kwargs)

  • get_relationship(source_uid, target_uid, relationship_name=None)

  • delete_unit(uid) and delete_relationship(...)

  • search_similarity_in_graph(query_text=None, query_embedding=None, query_image_path=None, top_k=5, ms_names=None, return_score=False)

  • get_multi_retriever()

  • save_graph(directory_path) and load_graph(directory_path)

  • connect_to_l2(...) and close() for RocksDB tiered-paging lifecycle

Canonical tower spaces

MemorySpaceRegistry and TowerSpace define canonical names used by the three retrieval towers:

  • hierarchical_memory

  • hierarchical_memory:L0_Observation

  • hierarchical_memory:L1_Summary

  • hierarchical_memory:L2_Insight

  • entity_relation

  • entity_relation:entities

  • entity_relation:mentions

  • entity_relation:relations

  • episodic_memory