Quick Start

Start with the current MemoryUnit, SemanticMap and SemanticGraph APIs.

Minimal semantic graph

This example uses the small MiniLM preset and disables realtime SPLADE generation so first-run setup stays modest. Creating SemanticMap loads an embedding model; if it is not cached, sentence-transformers may download it.

from mandol import MemoryUnit, SemanticGraph, SemanticMap

semantic_map = SemanticMap(
    embedding_model_name="all-MiniLM-L6-v2",
    use_flash_attention=False,
)
graph = SemanticGraph(semantic_map_instance=semantic_map)

graph.add_unit(
    MemoryUnit(
        uid="msg_001",
        raw_data={"text_content": "Zhang San travelled to Beijing today."},
        metadata={"timestamp": "2026-06-21T09:00:00"},
    ),
    space_names=["demo"],
    generate_sparse_embedding=False,
)
graph.add_unit(
    MemoryUnit(
        uid="msg_002",
        raw_data={"text_content": "He will discuss the Q2 delivery plan."},
        metadata={"timestamp": "2026-06-21T09:05:00"},
    ),
    space_names=["demo"],
    generate_sparse_embedding=False,
)

graph.add_relationship("msg_001", "msg_002", "NEXT")

hits = graph.search_similarity_in_graph(
    query_text="Where did Zhang San go?",
    top_k=3,
    ms_names=["demo"],
    return_score=True,
)

for unit, score in hits:
    print(f"{score:.3f} {unit.uid}: {unit.text_cached}")

Multi-method retrieval

Use MultiRetriever.smart_search for BM25, SPLADE, cosine retrieval, fusion and optional reranking. The example avoids reranking so it does not load a cross-encoder model.

from mandol.retrieval import MultiRetriever

retriever = MultiRetriever(graph)
results = retriever.smart_search(
    "Where did Zhang San go?",
    methods=["bm25", "cosine"],
    top_k=5,
    rerank_method=None,
    space_names=["demo"],
)

for unit, score in results:
    print(score, unit.uid)

Save and load

graph.save_graph("./memory_snapshot", build_sparse_vectors=False)

restored = SemanticGraph.load_graph(
    "./memory_snapshot",
    embedding_model_name="all-MiniLM-L6-v2",
    use_flash_attention=False,
)

Use SemanticGraph.save_graph for complete snapshots. SemanticMap.save_map is available for resident map-only persistence, but it does not preserve graph topology and fails closed while tiered paging is enabled.