HoloCortex - A peer-to-peer knowledge graph for agents to share ideas and grow together

Distributed, production-hardened cognitive infrastructure for autonomous AI agents.

This is a standalone open-source repository inspired by Erasmus-X architecture concepts, neurosymbolic AI, hyperdimensional computing, CRDT-inspired graph synchronization, federated memory, and local-first AI systems. It is not a fork of Erasmus-X; optional adapters live under src/holocortex/adapters.

Vision

HoloCortex is a federated memory layer for autonomous AI:

• Every agent owns an independent local knowledge graph.
• Facts are represented as symbolic triples plus HDC hypervectors.
• Peers exchange signed CRDT-inspired graph deltas instead of relying on a central memory server.
• Provenance, confidence, timestamps, ownership, signatures, DIDs, and trust scores are first-class data.
• Contradictory facts can coexist until a resolver or human chooses a policy.
• Memory retrieval combines graph traversal and approximate HDC recall.
• Cognitive routing decides which peer should answer based on expertise, trust, locality, and graph neighborhood.

The target feel is: Git + Neo4j + HDC + federated AI cognition. This is not a chatbot memory layer, a vector database, or a centralized RAG service.

Core Capabilities

• Thread-Safe SQLite Store: Database writes are wrapped with robust reentrant locking (threading.RLock) to ensure integrity under high API concurrency.
• Dynamic SQL Query Optimization: Pushes graph filters directly down to native SQL statements to optimize memory footprint and fetch speed.
• WebRTC Direct P2P Transport: Establish serverless, direct over-the-internet peer connections using aiortc and Google STUN configurations.
• Robust WebSocket Relayed Sync: Includes socket-based synchronization channels for managed network topologies.
• Active Signaling Broker: Dedicated WebSocket handshaking endpoint /ws/p2p/signaling/{agent_id} to negotiate direct SDP/ICE connections.
• Optional API Key Security: Exposes secure X-API-Key auth middleware protecting endpoints when configured in environment.
• Futuristic Graph Visualizer: Fully redesigned dark glassmorphism visualizer featuring real-time node count metrics, vibrant HSL gradients, and comprehensive provenance inspectors.
• Pydantic Schemas: Precise data models for nodes, edges, provenance, queries, and graph deltas.
• HDC Hyperdimensional Vectors: Deterministic hypervector bindings, bundles, permutations, and approximate search capabilities.
• Ed25519 Cryptographic Trust: Secure digital signing of graph deltas, proof snapshot checks, and agent Decentralized Identifiers (DIDs).
• Cognitive Routing Mesh: Peer expertise ranking based on trust, proximity, and semantic expertise.
• Conflict Resolver: Rank contradictory triples using confidence, provenance chains, and peer reputation.

Install

python -m pip install -e ".[dev]"

Run The API

uvicorn holocortex.api.server:app --reload

Open:

• API health: http://localhost:8000/health
• OpenAPI docs: http://localhost:8000/docs
• Graph payload: http://localhost:8000/api/v1/graph
• Filtered graph: http://localhost:8000/api/v1/graph?owner=agent_alpha&namespace=default
• Hybrid search: http://localhost:8000/api/v1/search/hybrid?q=memory
• Resolver ranking: http://localhost:8000/api/v1/reasoning/resolve?subject=A&predicate=is

To secure endpoints with API Keys, set HOLOCORTEX_API_KEY in your environment.

Run The Premium Visualizer

Start the API first:

uvicorn holocortex.api.server:app --reload

Then serve the premium dark-themed static visualizer from another terminal:

python -m http.server 3000 --directory frontend/graph_visualizer

Open http://localhost:3000. Use the peer and namespace filters in the sidebar to inspect subsets of the graph, and click nodes or edges to inspect provenance.

Killer Demo

Run the federated cognition demo:

python examples/federated_cognition_demo.py

What it shows:

• Two autonomous agents discover each other and exchange DIDs/public keys.
• Each agent writes independent local memories.
• They exchange signed graph deltas and converge without a central memory server.
• A contradiction is preserved instead of overwritten.
• The resolver ranks the competing facts by confidence, trust, temporal freshness, and provenance.
• One agent delegates a query to the other and uses the answer in a collaborative final response.

Docker

docker compose up --build

Then open:

• API: http://localhost:8000
• Visualizer: http://localhost:3000

Insert A Fact

python examples/insert_fact_demo.py

Or call the API:

{
  "subject": "Erasmus-X",
  "predicate": "implements",
  "object": "modular memory shards",
  "confidence": 0.92,
  "source": "github",
  "agent_id": "agent_alpha"
}

POST it to /api/v1/memory/facts.

Two-Agent Sync Demo

python examples/two_agent_sync_demo.py

This starts two local peers, inserts independent facts, gossips signed graph deltas, and shows that both peers converge while preserving contradictory facts.

Repository Layout

src/holocortex/
  graph/       schemas, store, query, traversal, SQL filters
  memory/      HDC encoder, memory layers, local embeddings, retrieval
  p2p/         peer, protocol, transport, WebRTC, WebSocket, discovery
  trust/       provenance, reputation, signatures, verification
  routing/     cognitive peer routing
  reasoning/   symbolic reasoning, temporal reasoning, resolver
  adapters/    Erasmus-X integration
  api/         FastAPI server, routes, websocket hubs, security
  utils/       shared helpers
frontend/graph_visualizer/
  premium dark-themed visualizer
docs/
  architecture, API, roadmap
examples/
  insertion, P2P sync, and WebRTC demos
tests/
  core MVP tests and WebRTC sync validations

Build A Clean Release Zip

powershell -ExecutionPolicy Bypass -File scripts/build_release_zip.ps1

The generated archive excludes .git, __pycache__, *.pyc, local envs, caches, databases, and build outputs.

Design Notes

HoloCortex is designed to remain offline-first. Embedding integrations are optional adapters for local models such as sentence-transformers, Nomic, Jina, E5, or GGUF embedders; the core never requires a hosted embedding API.

Graph delta sync is CRDT-inspired rather than a complete CRDT. Edges have unique ids, merges are append-friendly, vector clocks track causal progress, tombstones propagate removals, and contradictory triples are preserved. Later resolver policies rank, cluster, or suppress facts based on confidence, provenance, and peer trust without erasing the underlying evidence.

See docs/architecture.md, docs/api.md, and docs/roadmap.md.