bungraph

bungraph

Docs: https://anentrypoint.github.io/bungraph/

Turnkey temporal context graph on libsql for AI agents. A 1:1 JavaScript port of Graphiti built on:

• libsql — single-file embedded graph + vector (F32_BLOB + vector_top_k) + FTS5 keyword search. Zero external servers.
• Local embeddings — Xenova/all-MiniLM-L6-v2 (384d) via transformers.js. No API keys.
• Pluggable LLM — default uses your local claude CLI (claude -p). Set BUNGRAPH_LLM_PROVIDER=acp + BUNGRAPH_ACP_COMMAND="opencode acp" (or any Agent Client Protocol agent: kilo, gemini-cli, custom) to route all extraction/dedupe/summary calls through an ACP stdio subprocess via @agentclientprotocol/sdk. Long-lived session, mutex-serialized turns, auto-allow permissions, JSON output parsed from streamed agent_message_chunk text.

Quick start

One command, three modes. Default is MCP.

# MCP stdio server (default — for Claude Code, Cursor, IDE plugins)
bunx bungraph
# or explicit:
bunx bungraph --mcp

# HTTP REST server (graphiti upstream server parity)
bunx bungraph --serve --port 8000

# CLI one-shots
bunx bungraph add "Alice Johnson joined Acme Corp as a software engineer in March 2024." --source text
bunx bungraph search "What is Alice's current role?"

Register as a permanent MCP server:

claude mcp add -s user bungraph -- bunx bungraph

MCP tools (21)

Ingestion: add_episode, add_episode_bulk, add_triplet Search: search, search_nodes, search_facts, search_communities, search_episodes — all accept as_of for bitemporal queries Retrieval: get_episodes, get_node, get_edge, get_episode Communities: build_communities, remove_communities Sagas: create_saga, summarize_saga Mutation: delete_episode, delete_entity_edge, delete_entity_node, clear_graph Observability: debug_state — returns in-process subsystem snapshot (tx stats, writer mutex, LLM inflight, embeddings cache, store URL)

All tool inputs validated with strict zod schemas; unknown keys rejected. Every tool returns structuredContent alongside human-readable content; failures return RFC 9457-style problem descriptors.

HTTP endpoints

POST /messages · POST /entity-node · DELETE /entity-edge/:uuid · DELETE /group/:gid · DELETE /episode/:uuid · POST /clear · POST /search (accepts as_of) · GET /entity-edge/:uuid · GET /episodes/:gid · POST /get-memory · POST /build-communities · POST /triplet · GET /healthcheck · GET /debug/state

Errors conform to RFC 9457 application/problem+json: {type, title, status, detail, issues?}. Bodies capped at 4 MB; invalid JSON returns 400; validation failures surface zod issues.

Bitemporal queries

Every edge carries valid_at (when the fact became true in the world) and expired_at (when the system learned it was no longer true). Search accepts as_of: <ISO-8601> and returns only edges active at that moment:

await graph.search('who does Alice work for', { asOf: '2024-06-01T00:00:00Z' });

Transaction safety: every multi-statement upsert runs through withTx with BEGIN IMMEDIATE semantics + writer mutex + jittered SQLITE_BUSY retry (up to 8 attempts, exponential backoff capped at 2s).

Configuration

env	default	purpose
BUNGRAPH_LOG_LEVEL	info	trace/debug/info/warn/error/silent
BUNGRAPH_LLM_MAX_ATTEMPTS	5	retry budget for claude-cli failures
BUNGRAPH_LLM_TIMEOUT_MS	60000	per-call timeout
BUNGRAPH_LLM_BACKOFF_CAP_MS	20000	max backoff between retries
BUNGRAPH_CLAUDE_BIN	auto-detect	override path to claude binary
BUNGRAPH_LLM_PROVIDER	claude-code	claude-code or acp
BUNGRAPH_ACP_COMMAND	—	ACP agent stdio command, e.g. opencode acp, kilo acp, gemini acp
BUNGRAPH_ACP_ARGS	—	extra args (JSON array or space-separated) appended to command
BUNGRAPH_DEBUG_ACP	off	log ACP subprocess stderr
BUNGRAPH_STUB_EMBEDDINGS	off	stub deterministic vectors for offline tests
BUNDAG_SKIP_LLM	off	skip LLM-dependent branches of test.js

Logs are JSON lines on stderr with subsystem routing; API keys and authorization/apiKey/token/secret/password/bearer fields redacted automatically.

Pipeline

Each episode goes through:

• Entity extraction — LLM via ACP extracts named entities (message/text/json source-type-specific prompts)
• Semantic dedup — vector-similar existing nodes surfaced via vector_top_k, exact/loose-name match first, then LLM dedupe prompt
• Edge extraction — LLM extracts fact triples between resolved entities with ISO-8601 validity windows
• Temporal resolution — LLM detects duplicates + contradictions against existing edges; contradicted edges get expired_at + invalid_at set
• Attribute + summary extraction — per-entity attribute extraction (if schema provided) + batch entity summaries
• Persistence — nodes/edges written to libsql with vector + FTS indices
• Episodic edges — MENTIONS edges created from episode to each resolved node
• Optional — saga linkage (HAS_EPISODE + NEXT_EPISODE), community refresh

Search

Combines vector_top_k (F32 cosine) + FTS5 (BM25) via Reciprocal Rank Fusion. Rerankers: rrf, mmr, node_distance, episode_mentions, cross_encoder (via ACP).

16 recipes available from upstream: NODE_HYBRID_SEARCH_RRF, NODE_HYBRID_SEARCH_MMR, NODE_HYBRID_SEARCH_NODE_DISTANCE, NODE_HYBRID_SEARCH_EPISODE_MENTIONS, NODE_HYBRID_SEARCH_CROSS_ENCODER, EDGE_HYBRID_SEARCH_* (5 variants), COMMUNITY_HYBRID_SEARCH_* (3 variants), COMBINED_HYBRID_SEARCH_* (3 variants), EPISODE_HYBRID_SEARCH_RRF.

Architecture vs. upstream Graphiti

Aspect	Graphiti (Python)	bungraph
Graph DB	Neo4j / Kuzu / FalkorDB / Neptune	libsql (single file)
Vector	Provider-specific	libsql F32_BLOB + vector_top_k
Keyword	Provider-specific (Lucene/FTS)	libsql FTS5
LLM	OpenAI / Anthropic / Gemini / Groq SDKs	local claude -p (no keys)
Embeddings	OpenAI / Voyage / Gemini / HF	transformers.js local (offline)
Cross-encoder	OpenAI / BGE / Gemini	local claude -p
Runtime	Python 3.10+	bun / node 18+

Docs site

The site at https://anentrypoint.github.io/bungraph/ is built by GitHub Actions from docs-src/ on every push to main. It uses flatspace as the build tool, the 247420 design system for styling (docs-src/theme/assets/), and vendors webjsx + rippleui locally — no CDN, no external network at runtime.

To build locally:

npx flatspace build      # reads flatspace.config.mjs, writes docs/

Content lives in docs-src/content/ as YAML. The theme is in docs-src/theme/.

License

Apache-2.0