NeuroWeave

Real-time knowledge graph memory for agentic AI platforms.

Agents that learn. Memory that compounds. Privacy that's provable.

Installation • Quickstart • Documentation • Architecture • Changelog

---

What This Is

NeuroWeave is an async Python library that transforms AI conversations into a live knowledge graph. As a user chats with an AI agent, NeuroWeave extracts entities and relationships from each message, materializes them into a graph, and lets the agent query that graph to recall facts, preferences, and connections.

from neuroweave import NeuroWeave

async with NeuroWeave(llm_provider="anthropic") as nw:
    # Agent feeds user messages — graph builds automatically
    await nw.process("My wife Lena and I are going to Tokyo in March")
    await nw.process("She loves sushi but I prefer ramen")

    # Query for relevant context
    result = await nw.query("what does my wife like?")
    # → nodes: [Lena, sushi]  edges: [Lena --prefers--> sushi]

Open http://localhost:8787 to watch the graph build in real time:

graph LR
    User((User)) -->|married_to| Lena((Lena))
    User -->|traveling_to| Tokyo((Tokyo))
    Lena -->|traveling_to| Tokyo
    User -->|named| Alex((Alex))
    User -->|prefers| ramen((ramen))
    Lena -->|prefers| sushi((sushi))
    User -->|experienced_with| Python((Python))
    User -->|has_children| children((children))

    style User fill:#6c63ff,color:#fff
    style Lena fill:#6c63ff,color:#fff
    style Alex fill:#6c63ff,color:#fff
    style Tokyo fill:#6c63ff,color:#fff
    style children fill:#6c63ff,color:#fff
    style Python fill:#4ade80,color:#000
    style sushi fill:#4ade80,color:#000
    style ramen fill:#4ade80,color:#000

---

Installation

pip install neuroweave-python

Or install from source:

git clone https://github.com/alexh-scrt/neuroweave.git
cd neuroweave
make install    # pip install -e ".[dev]"

---

Quickstart

As a Library (recommended)

import asyncio
from neuroweave import NeuroWeave

async def main():
    async with NeuroWeave(
        llm_provider="anthropic",
        llm_api_key="sk-ant-...",
    ) as nw:
        # Write path — extract knowledge, update the graph
        result = await nw.process("My wife Lena loves Malbec")
        print(f"Extracted {result.entity_count} entities")

        # Read path — structured query
        result = await nw.query(["Lena"], relations=["prefers"], max_hops=1)
        print(result.node_names())  # ['Lena', 'Malbec']

        # Read path — natural language (LLM translates to graph query)
        result = await nw.query("what does my wife like?")

        # Combined — process + query in one call (primary agent integration)
        context = await nw.get_context("remind me about dinner")
        print(context.relevant.node_names())

asyncio.run(main())

Mock Mode (no API key needed)

async with NeuroWeave(llm_provider="mock") as nw:
    ...

As a CLI

# With real LLM
export NEUROWEAVE_LLM_API_KEY=sk-ant-...
neuroweave

# With mock LLM (no API key needed)
NEUROWEAVE_LLM_PROVIDER=mock neuroweave

Demo Agent

python examples/demo_agent.py              # Canned demo (mock, no API key)
python examples/demo_agent.py -i           # Interactive mode
python examples/demo_agent.py --provider anthropic  # With real LLM

---

API Overview

Three Methods

Method	Purpose	Returns
process(message)	Extract knowledge, update graph	ProcessResult
query(...)	Query the graph (structured or NL)	QueryResult
get_context(message)	Process + query combined	ContextResult

Event Subscription

from neuroweave import EventType

async def on_new_entity(event):
    print(f"Discovered: {event.data['name']}")

nw.subscribe(on_new_entity, event_types={EventType.NODE_ADDED})

Visualization

nw = NeuroWeave(enable_visualization=True, server_port=8787)
# Graph visible at http://127.0.0.1:8787 with WebSocket live updates

Full documentation: neuroweave.readthedocs.io

---

Configuration

Three-tier system: field defaults → YAML → environment variables (highest priority).

# config/default.yaml
llm_provider: "anthropic"
llm_model: "claude-haiku-4-5-20251001"
graph_backend: "memory"       # or "neo4j" for persistent storage
server_host: "127.0.0.1"
server_port: 8787
log_level: "INFO"
log_format: "console"

# Neo4j settings (only when graph_backend: "neo4j")
neo4j_uri: "neo4j://localhost:7687"
neo4j_user: "neo4j"
neo4j_password: ""
neo4j_database: "neo4j"

# Environment variable overrides
NEUROWEAVE_LLM_PROVIDER=mock
NEUROWEAVE_LLM_API_KEY=sk-ant-...
NEUROWEAVE_LOG_FORMAT=json

---

Project Structure

neuroweave/
├── src/neuroweave/
│   ├── __init__.py              # Public exports: NeuroWeave, ProcessResult, ...
│   ├── api.py                   # NeuroWeave facade class (the public API)
│   ├── config.py                # Pydantic settings: YAML + env vars
│   ├── events.py                # EventBus async pub/sub
│   ├── logging.py               # structlog: console or JSON output
│   ├── main.py                  # CLI entry point
│   ├── extraction/
│   │   ├── llm_client.py        # LLMClient protocol + Mock + Anthropic
│   │   └── pipeline.py          # Message → ExtractionResult
│   ├── graph/
│   │   ├── store.py             # NetworkX graph + event emission
│   │   ├── backends/
│   │   │   ├── base.py          # AbstractGraphStore ABC (all async)
│   │   │   ├── memory.py        # MemoryGraphStore (NetworkX, async wrapper)
│   │   │   └── neo4j.py         # Neo4jGraphStore (persistent, native async)
│   │   ├── ingest.py            # ExtractionResult → graph nodes and edges
│   │   ├── query.py             # Structured query engine
│   │   └── nl_query.py          # NL → structured query via LLM
│   └── server/
│       └── app.py               # FastAPI: REST + WebSocket + Cytoscape.js
├── tests/                       # ~400 tests across 22 files
├── examples/
│   └── demo_agent.py            # Self-contained demo agent
├── docs/                        # MkDocs documentation (readthedocs.io)
├── config/default.yaml
├── static/index.html            # Cytoscape.js visualizer
├── pyproject.toml
├── mkdocs.yml
├── .readthedocs.yaml
├── LICENSE                      # Apache 2.0
└── CHANGELOG.md

---

Testing

make test           # All ~400 tests
make test-cov       # With coverage report
make lint           # Ruff linting
make format         # Auto-format

Test File	Tests	Coverage
test_smoke.py	2	Package imports, wiring
test_config.py	9	Defaults, YAML, env overrides
test_logging.py	8	Console/JSON output, filtering
test_graph.py	30	Node/edge CRUD, events, factories
test_extraction.py	30	JSON repair, mock LLM, resilience
test_ingest.py	13	Dedup, type mapping, growth
test_server.py	10	REST, WebSocket, health
test_e2e.py	22	Full POC proof: 5-msg → graph
test_live_updates.py	12	Event emission, server reflects graph
test_query.py	37	Structured queries, hop traversal
test_nl_query.py	38	NL query planner, parsing, fallback
test_events.py	33	EventBus lifecycle, timeout, errors
test_api.py	36	Facade lifecycle, process, query
test_integration.py	28	Full end-to-end with corpus
unit/test_neo4j_async.py	14	Async interface verification
unit/test_schema_bootstrap.py	7	Neo4j schema constraints
integration/test_async_store_in_event_loop.py	2	Canary: no event loop conflict

---

Dependencies

Core: anthropic ≥0.42, networkx ≥3.2, fastapi ≥0.115, structlog ≥25.5, pydantic-settings ≥2.7, uvicorn ≥0.34, websockets ≥16.0, pyyaml ≥6.0

Dev: pytest, pytest-asyncio, pytest-cov, httpx, ruff

Docs: mkdocs-material, mkdocstrings

---

License

Apache 2.0

---

NeuroWeave — Agents that learn. Memory that compounds. Privacy that's provable.