Skip to main content
Glama

agent-memory-hypergraph

Higher-Order Hypergraph Memory, Multi-Way Relational Reasoning & Temporal Consolidation for Autonomous AI Agent Swarms.

agent-memory-hypergraph provides higher-order episodic and semantic memory for multi-agent systems. While standard vector stores and pairwise knowledge graphs decompose multi-agent interactions into binary pairs or isolated vector embeddings, agent-memory-hypergraph models complex $n$-ary relationships ($k \ge 3$) connecting entities, tools, swarms, temporal states, and causal dependencies simultaneously.


1. Problem Statement

Autonomous multi-agent swarms face persistent memory degradation:

  • Lossy Binary Decomposition: In multi-agent problem solving, an action involves an agent, a tool, an environment state, an output observation, and a confidence metric. Pairwise graphs decompose this 5-way relationship into synthetic cliques ($O(k^2)$ edges), causing semantic drift and loss of causal cohesion.

  • Catastrophic Forgetting & Interference: Flat vector databases suffer from retrieval saturation and recency bias, lacking structural reinforcement.

  • Lack of Multi-Agent Epistemic Verification: When multiple agents report conflicting observations, pairwise graphs cannot model hyperclique tension or detect contradictory assertions over shared subgraphs.


Related MCP server: mnemosis-mcp

2. Why Existing Solutions Are Insufficient

Capability

Flat Vector DBs (Chroma/Pinecone)

Pairwise Knowledge Graphs (Neo4j/NetworkX)

agent-memory-hypergraph

$n$-ary Relationship Representation

—

Lossy clique expansion ($O(k^2)$)

Native Higher-Order Hyperedges ($k \ge 1$)

Spectral Centrality & Diffusion

—

Standard 2-node PageRank

Higher-Order Hypergraph PageRank & Laplacian

Causal Chain Pathfinding

—

Binary edge walks

Directed Hyperpath Reachability ($\text{tail} \to \text{head}$)

Temporal Consolidation

Hard TTL truncation

Static manual weights

Biological Ebbinghaus Decay & Semantic Promotion

Epistemic Swarm Conflict Detection

—

—

Hyperclique Dissonance & Tension Scoring

Architecture Overhead

Heavy client-server daemon

Heavy Java/JVM server

Zero-Dependency In-Process Python SDK & MCP


3. Architecture

flowchart TD
    subgraph MultiAgentSwarm["Multi-Agent Swarm Ingestion"]
        A1["Agent Alpha (Coder)"]
        A2["Agent Beta (Reviewer)"]
        Tools["Tools & Subprocesses"]
    end

    subgraph HypergraphCore["agent-memory-hypergraph Engine"]
        Incidence["Dual Incidence Registry (V ↔ E)"]
        SpectralEngine["Spectral Engine (Hypergraph PageRank & Random Walks)"]
        TemporalEngine["Ebbinghaus Consolidator (Decay & Reinforcement)"]
        ConflictEngine["Epistemic Conflict & Hyperclique Tension"]
        RetrievalEngine["H-Hop Subgraph & Causal Path Solver"]
    end

    subgraph Integration["Agent Consumption"]
        FastMCP["FastMCP JSON-RPC Server (7 Tools)"]
        RichCLI["Rich Interactive CLI"]
        LLMContext["Token-Optimized LLM Prompt Context"]
    end

    MultiAgentSwarm -->|n-ary Hyperedges| Incidence
    Incidence --> SpectralEngine
    Incidence --> TemporalEngine
    Incidence --> ConflictEngine
    Incidence --> RetrievalEngine
    RetrievalEngine --> LLMContext
    HypergraphCore --> FastMCP
    HypergraphCore --> RichCLI

4. Key Features

  1. Native Directed & Undirected Hyperedges: Model multi-way causal flows (${A, B, C} \to {D, E}$) and collaborative cliques without synthetic reification.

  2. Higher-Order Spectral Centrality: Hypergraph PageRank via power iteration on normalized transition kernels, discovering true knowledge hubs.

  3. Ebbinghaus Memory Consolidation: Biologically-inspired temporal decay ($w(t) = w_0 \cdot \exp(-\lambda \Delta t)$), access reinforcement, and episodic-to-semantic promotion.

  4. Causal Hyperpath Search: Reachability analysis from premise vertices to target consequences with automated explanatory gap identification.

  5. Epistemic Conflict & Tension Detection: Detects opposing agent assertions across shared subgraphs and scores hyperclique dissonance.

  6. FastMCP Server & Rich CLI: Built-in Model Context Protocol stdio server exposing 7 tools to Claude Code, OpenBot, Cursor, and custom orchestrators.


5. Installation

pip install agent-memory-hypergraph

For development:

git clone https://github.com/devsoniclk/agent-memory-hypergraph.git
cd agent-memory-hypergraph
pip install -e .[dev]

6. Quickstart Tutorial

Python SDK

from agent_hypergraph import (
    Hypergraph,
    HypergraphRetriever,
    RelationType,
    VertexType,
    compute_hypergraph_pagerank,
)

hg = Hypergraph("agent_swarm_memory")

# Ingest vertices
hg.add_vertex("Agent Nova", vertex_type=VertexType.AGENT, vertex_id="nova")
hg.add_vertex("Static Analyzer", vertex_type=VertexType.TOOL, vertex_id="tool_ast")
hg.add_vertex("SQL Injection Finding", vertex_type=VertexType.CLAIM, vertex_id="vuln_sql")
hg.add_vertex("Patch Deployment", vertex_type=VertexType.CONCEPT, vertex_id="patch")

# Ingest 3-ary directed causal hyperedge
hg.add_hyperedge(
    label="Vulnerability Audit",
    tail={"nova", "tool_ast"},
    head={"vuln_sql"},
    relation_type=RelationType.CAUSAL,
    confidence=0.98,
    source_agent="nova",
)

# Compute spectral centrality
ranks = compute_hypergraph_pagerank(hg)
print("Centrality scores:", ranks)

# Retrieve context for LLM prompt
retriever = HypergraphRetriever(default_max_hops=2)
verts, edges = retriever.expand_subgraph(hg, seed_vertices=["nova"])
prompt_markdown = retriever.format_for_prompt(verts, edges)
print(prompt_markdown)

Command Line Interface

# Ingest an agent vertex
agent-hypergraph insert-vertex "Nova Coordinator" -t agent --id nova

# Ingest a 3-way hyperedge
agent-hypergraph insert-edge "Code Review" -T nova -T tool_lint -H pr_approved -r causal

# Query multi-hop context
agent-hypergraph query nova --hops 2

# Inspect PageRank scores
agent-hypergraph rank

# Launch stdio MCP server for AI clients
agent-hypergraph serve

7. Performance Benchmarks

Benchmarked on Apple Silicon (M-series, Python 3.9):

Benchmark Metric

Result

Ingestion Throughput

37,822 edges / sec ($n=1,000$ vertices, $500$ 4-ary hyperedges)

PageRank Power Iteration

51.21 ms (1,000 vertices, 50 iterations, tol=$10^{-6}$)

2-Hop Neighborhood Query

0.03 ms / query ($30 \mu\text{s}$ retrieval latency)

Test Suite Execution

39/39 passing (0.33s total test duration, 93% code coverage)


8. Development & Testing

# Run unit and integration tests with coverage
PYTHONPATH=. pytest --cov=agent_hypergraph tests/

9. Roadmap

  • Higher-order incidence structure and dual hyperedge indexing

  • Hypergraph random walk and PageRank power iteration

  • Ebbinghaus temporal decay and episodic promotion

  • Causal hyperpath search and explanatory gap detection

  • Epistemic contradiction detector and hyperclique tension metrics

  • FastMCP stdio server and Rich CLI

  • ZK hyperedge membership proofs (integration with agent-zk-trace-verifier)

  • Persistent SQLite / DuckDB backend adapter for billion-edge graphs


10. License

Released under the MIT License. Copyright (c) 2026 Lakshitha Dananjaya.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides persistent, graph-based memory for AI agents via MCP, enabling semantic search, wikilink traversal, reminders, and injection protection.
      9
      34
      Apache 2.0
    • A
      license
      C
      quality
      A
      maintenance
      Provides AI agents with a human-inspired memory layer via MCP, enabling episodic and semantic memory recall, forgetting curves, consolidation, and contradiction detection. It integrates with MCP clients to offer local-first, dependency-free memory management.
      98
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides local-first persistent memory with a typed knowledge graph and bounded multi-hop retrieval via MCP, letting coding agents and local LLM systems store, search, and recall facts across sessions without hosted services or model dependencies.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to store and recall an append-only, hash-chained memory with citation-backed semantic search, fact verification, contradiction detection, and replay/audit capabilities through local MCP tools.
      1
      AGPL 3.0