agent-memory-hypergraph
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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) |
|
$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 --> RichCLI4. Key Features
Native Directed & Undirected Hyperedges: Model multi-way causal flows (${A, B, C} \to {D, E}$) and collaborative cliques without synthetic reification.
Higher-Order Spectral Centrality: Hypergraph PageRank via power iteration on normalized transition kernels, discovering true knowledge hubs.
Ebbinghaus Memory Consolidation: Biologically-inspired temporal decay ($w(t) = w_0 \cdot \exp(-\lambda \Delta t)$), access reinforcement, and episodic-to-semantic promotion.
Causal Hyperpath Search: Reachability analysis from premise vertices to target consequences with automated explanatory gap identification.
Epistemic Conflict & Tension Detection: Detects opposing agent assertions across shared subgraphs and scores hyperclique dissonance.
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-hypergraphFor 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 serve7. 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Cross-session memory for AI agents with a Source Receipt for every memory, over MCP.
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides persistent, graph-based memory for AI agents via MCP, enabling semantic search, wikilink traversal, reminders, and injection protection.934Apache 2.0
- AlicenseCqualityAmaintenanceProvides 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.981MIT
- AlicenseNot gradedqualityBmaintenanceProvides 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
- AlicenseNot gradedqualityCmaintenanceEnables 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.1AGPL 3.0