Fallen-8 is an in-memory graph database written in C# (.NET 10), built for raw speed on heavy graph algorithms.
It has no query language — no Cypher, no Gremlin, and none is planned. Queries are C#: small delegate fragments compiled at runtime, or precompiled stored queries. That is a deliberate choice for the era of code-generating agents — an agent emits a C# fragment, the engine compiles and runs it in-process at full speed, with no query-language layer in between. This is the .NET Core evolution of the original fallen-8.
📚 Full documentation: https://cosh.github.io/fallen-8-core/ — a fast, searchable site with a deep dive per feature and the interactive API reference.
Each feature has a deep-dive doc — follow the link.
- Graph model — a directed property graph; typed properties on vertices and edges, all mutation through a serialized transaction queue.
- Delegates, not a query language — filters and cost functions are runtime-compiled C# fragments; the defining design decision.
- Path finding — shortest/weighted paths with delegate filter and cost functions (BLS, Dijkstra).
- Subgraphs — extract a pattern-matched subset as a standalone graph, recalculate it when the source changes, nest and persist it.
- Graph analytics — PageRank, connected components, communities, degree centrality, triangle counting, with optional property write-back.
- Stored queries — register a vetted, compiled query once and invoke it by name — no dynamic code at call time.
- Indexes — dictionary, range, fulltext, spatial R-Tree, and vector kNN, all as plugins.
- Vector search — exact k-nearest-neighbour over
float[]embeddings (cosine, dot product, L2). - Semantic traversal — embeddings as element state; a
code-free
semanticblock steers paths and subgraphs by similarity. - Bulk import/export — stream whole graphs as newline-delimited JSON that round-trips exactly.
- Live change feed — committed mutations as Server-Sent Events, in commit order, with in-band resync.
- Save games — checkpoints tracked by a registry that drives startup, on top of a write-ahead log.
- Namespaces — many isolated graphs in one Fallen-8, addressable under
/ns/{name}/…. - Observability: opt-in Prometheus/OTLP metrics and traces, a
graph-shape snapshot, and health probes for one instance, plus a multi-tenant consumer stack
(Collector, Prometheus, Tempo, Loki, Grafana) that collects what many instances push into one
Grafana pane, keyed by tenant/instance/namespace; on by default with
npm run env:up. - REST API — a versioned HTTP surface with an OpenAPI document and an interactive Scalar reference.
- Plugins — indices, algorithms, and services are all discovered plugins.
- Plugin registration — add runtime algorithm and graph-function plugins by authoring C# source (compiled, contract-validated, namespace-scoped) instead of uploading a DLL.
- F8 Studio — a browser UI to browse, query, visualize, and author the C# delegates, with a natural-language assist that runs through your instance by default (or a browser-direct custom model backend).
- MCP server — a Model Context Protocol surface so AI agents call Fallen-8 as typed tools; small and token-frugal, read-only by default, with tiered opt-in writes and three auth modes up to OAuth 2.1.
- Security — optional all-or-nothing API key; dynamic code execution is always on (queries are C#), so set a key before exposing the service off-box.
An in-memory engine with a thin REST app around it. AI agents reach it through the
MCP server; F8 Studio (the browser UI) and your own services call
the REST API directly. Under the hood the engine (fallen-8-core) holds the
graph in RAM, serializes every write through one writer thread, and runs the algorithms, while
the app (fallen-8-core-apiApp) is the thin HTTP layer that also serves F8 Studio. Engine and
app ship as one Docker unit alongside a model sidecar.
%%{init: {'theme':'base','themeVariables':{'fontFamily':'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace','lineColor':'#666666'}}}%%
flowchart TB
agents["AI agents"]:::client
studio["F8 Studio<br/>browser UI"]:::client
services["Your services / code"]:::client
mcp["MCP server<br/>fallen-8-mcp"]:::mcp
subgraph unit["Fallen-8 · one Docker unit"]
direction TB
rest["REST API<br/>fallen-8-core-apiApp · thin layer"]:::api
engine["In-memory graph engine<br/>fallen-8-core"]:::engine
rest --> engine
end
sidecar["Model sidecar<br/>Ollama"]:::ext
obs["Observability<br/>Collector · Prometheus · Tempo · Loki · Grafana"]:::obs
agents -->|MCP| mcp
mcp -->|HTTP| rest
studio -->|HTTP| rest
services -->|HTTP| rest
rest -.->|embeddings + chat| sidecar
rest -.->|OTLP push| obs
mcp -.->|OTLP push| obs
classDef client fill:#45494D,stroke:#666666,color:#FEFEFE
classDef mcp fill:#E2001A,stroke:#FC0606,color:#FEFEFE
classDef api fill:#141516,stroke:#45494D,color:#FEFEFE
classDef engine fill:#060606,stroke:#45494D,color:#FEFEFE
classDef ext fill:#141516,stroke:#666666,color:#C6C7C8,stroke-dasharray:5 4
classDef obs fill:#141516,stroke:#E2001A,color:#C6C7C8
style unit fill:#000000,stroke:#E2001A,stroke-width:1.5px,color:#C6C7C8
Full details — the writer thread, plugin system, durability, and the model sidecar — are in docs/architecture.md.
One command brings up everything — engine, REST API, F8 Studio, the MCP server for agents, and the model sidecar — with every feature on and no authentication in the way (same on macOS, Linux, and Windows PowerShell):
npm run env:upThen open F8 Studio at http://localhost:8080 and load a sample graph from the Samples screen. The MCP server is on http://localhost:8090 for AI-agent clients (read-only by default).
Every other way to run it — a bare dotnet run, the configuration keys, the security
switches, GPU acceleration, offline model pre-seeding — is in
docs/running.md.
F8 Studio ships a one-click sample gallery: curated graphs (a karate club, an Active-Directory attack surface, a movie-recommendation graph, world air routes, Fallen-8's own dependency graph) that load in a click and come styled, indexed, and ready to explore. Each one is a guided tour of a different feature — analytics, weighted paths, semantic search, canvas visualization. See the gallery walkthrough, with screenshots and example queries, in docs/samples.md.
Agents reach Fallen-8 through the MCP server — a separate deployable that exposes the graph
as Model Context Protocol tools any MCP client (Claude Code,
Claude Desktop, IDE agents) can call. It is a small, token-frugal tool surface, read-only by
default, with opt-in write/admin tiers and three auth modes (anonymous-loopback, static bearer,
OAuth 2.1). It comes up with npm run env:up on http://localhost:8090 — anonymous and
read-only, matching the local dev environment's no-auth posture. Point a client at it:
claude mcp add --transport http fallen8 http://localhost:8090For a real (off-box) deployment, set a token and enable the tiers you need — full guide in docs/mcp-server.md.
Common snags — first-start model pulls, the embedding provider, missing-key 401s, GPU detection — and their fixes are in docs/troubleshooting.md.
The full documentation set is the searchable site at
https://cosh.github.io/fallen-8-core/. Its sources live in docs/ (a Starlight site) and
deploy on every push to main.
Copyright (c) 2011-2026 Henning Rauch
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.