kg-fuse 0.3.2

FUSE filesystem for Knowledge Graph - mount your knowledge graph as a filesystem

Knowledge Graph FUSE Driver

Mount the knowledge graph as a filesystem.

Installation

Prerequisites

System FUSE library (required):

sudo pacman -S fuse3       # Arch
sudo apt install fuse3     # Debian/Ubuntu
sudo dnf install fuse3     # Fedora

kg CLI (for OAuth setup):

npm install -g @aaronsb/kg-cli

Install kg-fuse

pipx install kg-fuse

Upgrade

pipx upgrade kg-fuse

Setup

Create OAuth credentials (one-time):

kg oauth create --for fuse

This writes credentials to ~/.config/kg-fuse/config.toml.

Usage

# Mount (reads credentials from config)
kg-fuse /mnt/knowledge

# Or run in foreground for debugging
kg-fuse /mnt/knowledge -f

Unmount:

fusermount -u /mnt/knowledge
# or just Ctrl+C if running in foreground

Manual Credentials

You can also pass credentials directly:

kg-fuse /mnt/knowledge \
  --api-url https://kg.example.com/api \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_SECRET

Filesystem Structure

/mnt/knowledge/
├── ontology-a/          # Each ontology is a directory
│   ├── doc1.md          # Documents in that ontology
│   └── doc2.md
└── ontology-b/
    └── doc3.md

Read: Browse Documents

ls /mnt/knowledge/                    # List ontologies
ls /mnt/knowledge/my-ontology/        # List documents
cat /mnt/knowledge/my-ontology/doc.md # Read document

Write: Ingest Documents (future)

cp report.pdf /mnt/knowledge/my-ontology/
# File "disappears" into ingestion pipeline
# Creates job, extracts concepts, links to graph

Debug Mode

kg-fuse /mnt/knowledge --debug -f

Architecture

The FUSE driver is an independent client that:

• Authenticates via OAuth (like CLI, MCP server)
• Makes HTTP requests to the API server
• Caches directory listings (30s TTL)
• Defaults to localhost:8000 if unconfigured (fail-safe: won't accidentally query external endpoints)

See ADR-069 for full design rationale.