Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ossrandom/kgraph) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

kgraph

Knowledge graph for AI coding agents

Your AI agents forget everything between sessions.
kgraph gives them persistent memory — a graph of interconnected notes that grows as they work.

Setup

Install

npm i -g @ossrandom/kgraph

Initialize a project

Run inside any git repository:

cd your-project
kgraph init

That's it. Your AI sessions now have persistent project memory.

What `init` does

Detects your git remote (project identity)
Starts a local server (or connects to remote if KGRAPH_SERVER is set)
Installs hooks for Claude Code, Copilot, Codex, VS Code
Registers the project

Use a remote server instead

KGRAPH_SERVER=https://kgraph.yourdomain.com kgraph init

No local server started — hooks point to your remote instance.

How It Works

Session Start                          Session End
     │                                      │
     ▼                                      ▼
  hook fires                           hook fires
     │                                      │
  reads git remote                     (future: extract
     │                                  notes from session)
  POST /api/hook/SessionStart               │
     │                                  POST /api/hook/Stop
  server looks up project                   │
     │                                  server stores
  returns last 10 notes                 new knowledge
  as additionalContext                      │
     │                                  graph updated
  agent starts with                         │
  full project knowledge               next session
     ▼                                  gets it all
  zero-config context                       ▼

Every AI coding tool that supports hooks (Claude Code, Copilot, Codex) gets the same context — the hook script is universal.

Web UI

Open http://localhost:3456 (or your remote URL) in any browser.

Graph View

WebGPU renderer (Chrome/Edge) with WebGL 2 fallback
ForceAtlas2 layout in Web Worker
Hover to highlight connections, tap to open notes
Pinch-to-zoom, pan, drag on mobile

Notes

Browse folder tree in sidebar
View rendered markdown with clickable [[wikilinks]]
Edit notes with author/tags metadata
Full-text search across all notes

Mobile

Installable PWA (Add to Home Screen)
Bottom tab bar: Graph / Notes / Note
Touch-optimized graph interaction

CLI

kgraph init [remote] [--name <n>]           One-command setup
kgraph serve [--port <port>] [--daemon]     Start server
kgraph project register [remote] [--name]   Register a project
kgraph project list                         List projects
kgraph hooks install [--claude|--all]       Install hooks
kgraph hooks update                         Update hook scripts
kgraph hooks remove [--claude|--all]        Remove hooks
kgraph hooks status                         Show what's installed

Hook Platforms

kgraph hooks install --claude     # Claude Code
kgraph hooks install --copilot    # GitHub Copilot
kgraph hooks install --codex      # OpenAI Codex
kgraph hooks install --vscode     # VS Code
kgraph hooks install --all        # All (default)

Import / Export

From the UI

Export: Click ↓ Export in the top bar — downloads all notes as a ZIP
Import: Click ↑ Import — upload a ZIP of markdown files

From the API

# Export
curl https://kgraph.yourdomain.com/api/projects/my-project/export -o notes.zip

# Import
curl -X POST https://kgraph.yourdomain.com/api/projects/my-project/import \
  --data-binary @notes.zip

Notes Format

Plain markdown with optional YAML frontmatter. [[wikilinks]] create graph edges.

---
author: architect
tags: [auth, security]
---

Using JWT with refresh tokens for stateless auth.

Decision driven by [[security-constraints]] and
designed to work across [[api-gateway]] instances.

Notes live on disk at ~/.kgraph/projects/<name>/notes/. SQLite is a derived index.

API

All endpoints under /api/. Optional auth via Authorization: Bearer <key>.

Method	Endpoint	Description
`GET`	`/api/projects`	List projects
`POST`	`/api/projects/register`	Register `{ remote, name? }`
`GET`	`/api/projects/:p/notes/*key`	Read note + links
`PUT`	`/api/projects/:p/notes/*key`	Create/update `{ content, author?, tags? }`
`DELETE`	`/api/projects/:p/notes/*key`	Delete note
`GET`	`/api/projects/:p/graph`	Full graph `{ nodes[], edges[] }`
`GET`	`/api/projects/:p/tree`	Folder tree
`GET`	`/api/projects/:p/search?q=...`	Full-text search
`GET`	`/api/projects/:p/export`	Download ZIP
`POST`	`/api/projects/:p/import`	Upload ZIP
`GET`	`/health`	Health check

MCP endpoint: /mcp (Streamable HTTP)

Configuration

Variable	Default	Description
`KGRAPH_SERVER`	—	Remote server URL (skip local server)
`KGRAPH_PORT`	`3456`	Local server port
`KGRAPH_DATA_DIR`	`~/.kgraph`	Data directory
`KGRAPH_API_KEY`	—	API authentication key

Storage

~/.kgraph/
├── registry.db              # git remote → project mapping
├── hooks/
│   ├── hook.sh              # Unix hook (bash + curl)
│   └── hook.mjs             # Windows hook (Node.js)
└── projects/
    └── my-project/
        ├── index.db          # SQLite with FTS5
        └── notes/            # Markdown files
            ├── architecture/
            │   └── overview.md
            └── api-design.md

Runtime

Works on Bun (recommended) and Node.js 20+.

	Bun	Node.js 20+
SQLite	Built-in (`bun:sqlite`)	`better-sqlite3` (auto-installed)
Extra deps	None	1 optional

# Bun
bun run src/index.ts serve

# Node
node dist/cli.mjs serve

# Via global install
kgraph serve

Deploy

With Caddy (recommended)

kgraph.yourdomain.com {
    reverse_proxy localhost:3456
}

Caddy auto-provisions HTTPS. WebGPU requires HTTPS.

With Docker

docker run -d -p 3456:3456 -v kgraph-data:/data ghcr.io/randomcodespace/kgraph

As a systemd service

curl -sf https://raw.githubusercontent.com/RandomCodeSpace/kgraph/main/deploy/setup.sh | bash

GitHub · npm · Issues

MIT License

@ossrandom/kgraph