Skip to content
Back to search

knowledge-graph-system

Kappa Graph — κ(G). A semantic knowledge graph where knowledge has weight. Extracts concepts, measures grounding strength, preserves disagreement, traces everything to source.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aaronsb--knowledge-graph-system/badge.svg)](/listings/aaronsb--knowledge-graph-system)

HTML

<a href="/listings/aaronsb--knowledge-graph-system"><img src="/api/listings/aaronsb--knowledge-graph-system/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Install Client Tools

The `kg` CLI, MCP server (for AI assistants), and optional FUSE filesystem:

curl -fsSL https://raw.githubusercontent.com/aaronsb/knowledge-graph-system/main/client-manager.sh | bash

Or just the CLI: `npm install -g @aaronsb/kg-cli`

Deploy the Platform

Run your own knowledge graph backend:

curl -fsSL https://raw.githubusercontent.com/aaronsb/knowledge-graph-system/main/install.sh | bash

Or from source:

git clone https://github.com/aaronsb/knowledge-graph-system.git
cd knowledge-graph-system
./operator.sh init    # Interactive setup
./operator.sh start   # Start containers

See [Quick Start Guide](docs/operating/quick-start.md) for details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 170 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Kappa Graph — κ(G)
  2. ![License](https://img.shields.io/github/license/aaronsb/knowledge-graph-system)
  3. ![GitHub stars](https://img.shields.io/github/stars/aaronsb/knowledge-graph-system?style=social)
  4. ![Latest Release](https://img.shields.io/github/v/release/aaronsb/knowledge-graph-system?include_prereleases&label=version)
  5. A semantic knowledge graph that extracts concepts from documents, tracks how well-supported they are, and remembers where sources disagree.
  6. **[κ(G)](https://en.wikipedia.org/wiki/Connectivity_(graph_theory))** — vertex connectivity of a graph. The minimum number of connections you'd need to cut before the graph falls apart. A measure of how robust the structure is.
  7. Also **kg** — the unit of mass. Because knowledge here has weight. Grounding scores measure how heavy an idea is: well-evidenced claims carry more than thin ones. Contested concepts weigh differently than unchallenged ones.
  8. ![2D Force Graph Explorer](docs/media/screenshots/web-2d-force-graph-hero.png)
  9. ## Quick Start
  10. ### Install Client Tools
  11. The `kg` CLI, MCP server (for AI assistants), and optional FUSE filesystem:
  12. ```bash
  13. curl -fsSL https://raw.githubusercontent.com/aaronsb/knowledge-graph-system/main/client-manager.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 22 on GitHub
  14. ```
  15. Or just the CLI: `npm install -g @aaronsb/kg-cli`
  16. ### Deploy the Platform
  17. Run your own knowledge graph backend:
  18. ```bash
  19. curl -fsSL https://raw.githubusercontent.com/aaronsb/knowledge-graph-system/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 32 on GitHub
  20. ```
  21. Or from source:
  22. ```bash
  23. git clone https://github.com/aaronsb/knowledge-graph-system.git
  24. cd knowledge-graph-system
  25. ./operator.sh init # Interactive setup
  26. ./operator.sh start # Start containers
  27. ```
  28. See [Quick Start Guide](docs/operating/quick-start.md) for details.
  29. ## See It In Action
  30. ![2D Force Graph Explorer](docs/media/screenshots/web-2d-force-graph.png)
  31. *Interactive graph exploration with smart search, concept clustering, and relationship visualization*
  32. ![CLI with Inline Image Evidence](docs/media/screenshots/cli-search-with-images.png)
  33. *Command-line search returns concepts with source images rendered inline via chafa*
  34. ![Embedding Landscape with DBSCAN Clusters](docs/media/screenshots/web-embedding-landscape-clusters.png)
  35. *t-SNE embedding landscape with auto-detected clusters, named by topic via TF-IDF*
  36. ## What You Can Do
  37. **Ingest documents** — PDFs, markdown, images, text. The system extracts concepts, relationships, and evidence automatically.
  38. **Search by meaning** — "economic downturn" finds content about recessions, crashes, and crises even if those exact words aren't used.
  39. **Explore connections** — Find paths between concepts. See how ideas relate across documents.
  40. **Check confidence** — Every result includes grounding scores. Know what's well-supported vs. contested.
  41. **Trace sources** — Every concept links back to the original text or image that generated it.
  42. **Query via AI** — MCP server integration lets Claude and other assistants use the graph as persistent memory.
  43. **Navigate via filesystem** — Mount the graph as a FUSE filesystem. Use `ls`, `grep`, `find` on semantic space.
  44. ## Use Cases
  45. ![Obsidian viewing the knowledge graph via FUSE](docs/media/obsidian-use-case/obsidian-graph-view.png)
  46. *Obsidian's graph view rendering knowledge graph relationships via the FUSE filesystem — no plugin needed*
  47. **Research synthesis** — Ingest papers, find connections across them, see where authors disagree. Grounding scores tell you which claims have broad support.
  48. **Technical documentation** — Extract architecture concepts from diagrams, meeting notes, design docs. Query how components relate.
  49. **Agent memory** — Give AI assistants persistent, grounded memory. They can check confidence before making claims.
  50. ![Claude Desktop exploring the knowledge graph](docs/media/claude-desktop/claude-desktop-mcp.png)
  51. *Claude Desktop using MCP to search, explore relationships, and validate claims against the knowledge graph*
  52. **Spatial understanding** — Ingest place photos. The graph learns physical relationships without coordinates.
  53. **Compliance/audit** — Full provenance chain. Every concept traces to source evidence.
  54. ## Architecture
  55. ```
  56. Documents ──→ [FastAPI] ──→ LLM Extraction ──→ [PostgreSQL + AGE]
  57. │ │
  58. │ [graph_accel]
  59. │ in-memory traversal
  60. │ │
  61. [Garage S3] [AGE graph store]
  62. doc storage source of truth (ACID)
  63. │ │
  64. [React + D3] ←──── REST API ────→ [FastAPI]
  65. web visualization query + ingest
  66. │
  67. [CLI / MCP / FUSE]
  68. client interfaces
  69. ```
  70. - **PostgreSQL + Apache AGE** — Graph database with native openCypher queries. ACID transactions, schema integrity, vector search (pgvector).
  71. - **graph_accel** — In-memory graph traversal accelerator. A Rust PostgreSQL extension that maintains an adjacency structure in shared memory for instant BFS/shortest-path at any depth. AGE handles writes; graph_accel handles reads. Epoch-based invalidation ensures the read model is never stale. ([ADR-201](docs/architecture/database-schema/ADR-201-in-memory-graph-acceleration-extension.md))
  72. - **FastAPI** — Extraction pipeline and REST API
  73. - **React + D3** — Interactive graph visualization and exploration
  74. - **TypeScript CLI** — Command-line interface and MCP server for AI assistant integration
  75. - **Ollama** — Optional local inference (air-gapped operation)
  76. - **Garage** — S3-compatible object storage for document assets
  77. ## Documentation
  78. | Audience | Start Here |
  79. |----------|------------|
  80. | Understanding the concepts | [docs/concepts/](docs/concepts/) |
  81. | Deploying and operating | [docs/operating/](docs/operating/) |
  82. | Using the system | [docs/features/](docs/features/) |
  83. | Architecture decisions | [docs/architecture/](docs/architecture/) |
  84. 96 Architecture Decision Records document the design evolution.
  85. ## Background
  86. Most systems that store knowledge for retrieval — vector databases, RAG pipelines, knowledge graphs — optimize for finding relevant content. They can tell you *what* matches your query. They can't tell you how well-supported it is, whether sources disagree about it, or where the evidence actually came from.
  87. kg adds an epistemic layer on top of the graph. Every concept carries a **grounding score** computed from supporting vs. contradicting evidence — not a label, but a measurement. A concept backed by 47 sources with 12 contradictions scores differently than one with a single unchallenged mention. When sources disagree, the system preserves both sides rather than picking a winner.
  88. **Semantic diversity** provides a second signal. Well-established knowledge tends to connect across independent domains. Narrow claims that only reference each other score lower. In testing, Apollo 11 mission data showed 37.7% diversity across 33 concepts; moon landing conspiracy content showed 23.2% across 3.
  89. The system also handles images. Feed it street view photos and the extracted relationships ("next to", "across from", "visible from") naturally encode spatial topology — no coordinates needed.
  90. ### How It Compares
  91. | Capability | kg | GraphRAG | Zep/Graphiti | Cognee | Vector DBs |
  92. |------------|-------------|----------|--------------|--------|------------|
  93. | Contradiction detection | Native (mathematical) | LLM-dependent | Limited | No | No |
  94. | Grounding scores | Continuous -1 to +1 | Source citations only | No | No | Similarity only |
  95. | Semantic diversity | Yes (authenticity signal) | No | No | No | No |
  96. | Epistemic status | Per-relationship | No | No | No | No |
  97. | Temporal tracking | Ingestion epoch | No | Bi-temporal | No | No |
  98. | Emergent ontologies | Continuous annealing | One-shot communities | Temporal facts | Partial (event-driven) | N/A |
  99. | Multimodal ingest | Prose-bridge (own vector space) | Text-centric | Text-centric | Images/audio | Embeddings only |
  100. | FUSE filesystem | Yes | No | No | No | No |
  101. | Air-gapped operation | Yes (Ollama) | Cloud required | Cloud required | Local-capable | Some local |
  102. Each neighbor leads on a different axis: Zep/Graphiti on **bi-temporal** fact tracking, GraphRAG on adoption (its Leiden communities are the closest analog to annealing, but computed once at index time), and Cognee — the nearest architectural neighbor — on self-improving memory (event-driven, no epistemic layer). kg's temporal axis is deliberately narrower: it records *when evidence arrived* (ingestion epoch), not *when a fact was true* — because it holds **no truth values, only computed evidence**, and preserves contradictions rather than expiring them. That's a stance, not a gap — see [Computed Evidence over Asserted Truth](docs/concepts/computed-evidence-over-asserted-truth.md). What we haven't found a shipped peer for is the *combination*: continuous ontology annealing, a semantic FUSE surface, and an epistemic layer that measures confidence rather than just retrieving content.
  103. ## Why Try It
  104. If you need:
  105. - **Epistemic reliability** — knowing *how sure* you should be, not just *what* the answer is
  106. - **Contradiction awareness** — preserving disagreement rather than hiding it
  107. - **Full provenance** — tracing every claim to source evidence
  108. - **Local operation** — running without cloud API dependencies
  109. - **Unix integration** — using standard tools on semantic data
  110. kg was built for those requirements. Most alternatives optimize for retrieval accuracy or comprehensiveness. kg optimizes for *knowing what you know and how well you know it*.
  111. ## License
  112. **Apache License 2.0** — Use, modify, distribute freely. Patent grant included.
  113. ## Acknowledgments
  114. Built with [Apache AGE](https://age.apache.org/), [Model Context Protocol](https://modelcontextprotocol.io/), [FastAPI](https://fastapi.tiangolo.com/), and local inference via [Ollama](https://ollama.ai/).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.