Brainifai

A federated Personal Knowledge Graph (PKG) system. Data flows in from your work tools, gets routed by an AI orchestrator to specialized graph instances, and is served to Claude sessions via MCP.

How it works

Slack / GitHub / ClickUp / Apple Calendar / Twitter/X / Claude Code sessions
   |  fetch + normalize (incremental, cursor-based)
   v
Global Instance (~/.brainifai/)
   |  Ingestion pipeline -> MERGE into Kuzu (idempotent)
   |  AI Orchestrator (Claude Haiku) classifies + routes to children
   |  Event Bus (data.push)
   v
   +-- Coding Instance        -> PR context, decision logs, GitNexus code intelligence
   +-- Manager Instance       -> people context, meeting summaries
   +-- Project Manager        -> cross-project health, dependencies, Claude session history
   +-- EHR Instance           -> clinical queries (patients, meds, labs, conditions)
   +-- Researcher Instance    -> domain knowledge graph (entities, events, trends, metrics)
   +-- General Instance       -> broad cross-topic search
   v
MCP Servers (stdio, per-instance)
   v
Claude Sessions (Desktop or Claude Code)

Each instance has its own Kuzu database, its own set of context functions, and its own MCP server entry. Instances self-describe via config.json so the orchestrator knows where to route data.

Architecture

src/
  api/              Fastify REST API (graph visualization, ingestion triggers)
  cli/              CLI commands (init, status, list, describe, doctor, remove, ingest)
  context/          Context function registry, per-instance resolution
    functions/      Base tools + coding bridge + EHR + project-manager + researcher + engine primitives
  event-bus/        File-based pub/sub for inter-instance messaging
  graph-engine/     Reusable engine: schema-builder, write-path, resolver, extraction worker,
                    reads, embeddings, vector search, maintenance passes
  graphstore/       Legacy Kuzu adapters (EHR, project-manager, researcher schemas)
  hooks/            PreToolUse, SessionStart (engine working memory + legacy KG context)
  ingestion/        Slack, GitHub, ClickUp, Apple Calendar, Twitter/X, Claude Code,
                    project-manager, researcher-pipeline (self-contained ingestion)
  instance/         Instance model, templates, init, resolve, lifecycle, skill generator
  instances/        Per-instance type config (currently `general`: schema spec, retrieval functions)
  mcp/              MCP server, instance-aware tool registration
  shared/           Constants, logger, graphstore singleton
  viz/              React + Sigma.js graph visualization UI (engine viz tab)
  scripts/          Utilities (test-connection, seed-schema, longform-test, smoke-general)
bin/
  brainifai.js      CLI entrypoint

Data sources

Source	What's ingested
Slack	Channel messages, threads, reactions
GitHub	PRs, reviews, comments
ClickUp	Tasks, comments, status changes, docs
Apple Calendar	CalDAV events from iCloud
Claude Code	Session files, conversation summaries
Git repos	Commits, branches, dependencies (auto-scanned from ~/Projects)
Twitter/X	User timelines, search results (raw fetch + cookie auth)

All sources are optional — each is skipped if its credentials are not set. Ingestion is incremental and cursor-based.

Graph model

Base schema (all instances):

Node	Key	Represents
`Person`	`person_key`	A human across sources (`slack:U123`, `github:user`)
`Activity`	`(source, source_id)`	A message, PR, task, or calendar event
`Topic`	`name`	A keyword, hashtag, or label
`Container`	`(source, container_id)`	A channel, repo, list, or calendar

EHR schema (clinical instances):

Node	Key	Represents
`Patient`	`patient_id`	Demographics, birthdate, gender
`Encounter`	`encounter_id`	A clinical visit
`Condition`	`condition_id`	Diagnosis with onset/resolution dates
`Medication`	`medication_id`	Prescription with start/stop dates
`Observation`	`observation_id`	Lab result with value and units
`Procedure`	`procedure_id`	Clinical procedure with date
`Provider`	`provider_id`	Clinician or organization

Project Manager schema:

Node	Key	Represents
`Project`	`project_id`	A git repository with health scoring
`Commit`	`commit_id`	A git commit
`Dependency`	`dep_id`	Package dependency between projects

Researcher schema (domain knowledge instances):

Node	Key	Represents
`ResearchEntity`	`entity_key`	A company, product, person, project, or technology
`ResearchEvent`	`event_key`	A release, acquisition, partnership, or milestone
`ResearchTrend`	`trend_key`	An emerging theme or pattern
`ResearchMetric`	`metric_key`	A quantitative measure (benchmark, funding, etc.)

Instance types

Instances are bootstrapped from templates that configure which context functions are active:

Type	Sources	Context functions
coding	GitHub, Claude Code	Base 5 + `search_code`, `get_symbol_context`, `get_blast_radius`, `detect_code_changes`, `get_pr_context`, `get_decision_log`
manager	Slack, Calendar, ClickUp	Base 5 + `get_people_context`, `get_meeting_summary`
project-manager	Git repos (auto-scanned)	`search_projects`, `get_project_health`, `get_project_activity`, `get_cross_project_impact`, `find_stale_projects`, `get_dependency_graph`, `get_claude_session_history`
ehr	Static clinical data	`search_patients`, `get_patient_summary`, `get_medications`, `get_diagnoses`, `get_labs`, `get_temporal_relation`, `find_cohort`
researcher	Twitter/X (+ any source)	Base 4 + `get_landscape`, `get_entity_timeline`, `get_trending`, `get_entity_network`, `search_events`
general	All sources	Engine primitives: `working_memory`, `associate`, `recall_episode`, `consolidate`

Base tools (legacy non-EHR instances): search_entities, get_entity_summary, get_recent_activity, get_context_packet, ingest_memory.

The general instance uses the new graph engine — Atom/Entity/Episode schema, brain-inspired retrieval primitives (working memory, spreading activation, episodic recall, consolidation with optional supersedes), local embeddings, and scheduled maintenance passes (tier-recompute + alias-confirm so far).

The coding instance bridges to GitNexus for code intelligence — symbol context, call chains, and blast radius analysis.

Setup

Prerequisites

Node.js 20+

Install

git clone https://github.com/anagnole/Brainifai.git
cd Brainifai
npm install
cp .env.example .env

Configure sources

Edit .env with your credentials. All sources are optional.

Variable	Description
`KUZU_DB_PATH`	Override default DB path (`~/.brainifai/data/kuzu`)
`SLACK_BOT_TOKEN`	Slack bot token (`xoxb-...`)
`SLACK_CHANNEL_IDS`	Comma-separated Slack channel IDs
`GITHUB_TOKEN`	GitHub personal access token
`GITHUB_REPOS`	Comma-separated repos (`owner/repo`)
`CLICKUP_TOKEN`	ClickUp API token
`CLICKUP_LIST_IDS`	Comma-separated ClickUp list IDs
`APPLE_CALDAV_USERNAME`	iCloud email for CalDAV
`APPLE_CALDAV_PASSWORD`	App-specific password (generate here)
`APPLE_CALDAV_CALENDARS`	Calendar names to sync (empty = all)
`BACKFILL_DAYS`	Days to backfill on first run (default: `7`)
`TOPIC_ALLOWLIST`	Comma-separated keywords for topic extraction
`TWITTER_COOKIES`	Twitter/X session cookies (`auth_token=...; ct0=...`)
`TWITTER_USERNAMES`	Comma-separated Twitter handles to track
`TWITTER_SEARCH_QUERIES`	Comma-separated search queries

CLI

bin/brainifai.js init                    # Create global instance (~/.brainifai/)
bin/brainifai.js init --type coding      # Create project instance in cwd
bin/brainifai.js init --type researcher  # Create researcher instance in cwd
bin/brainifai.js status                  # Show instance health
bin/brainifai.js list                    # List all instances
bin/brainifai.js doctor                  # Diagnose connectivity issues
bin/brainifai.js twitter-auth            # Authenticate with Twitter/X
bin/brainifai.js ingest --instance <name> # Run dedicated instance ingestion
bin/brainifai.js ingest --instance <name> --extract-only  # Re-run LLM extraction only

Run

npm run ingest              # Fetch new data, upsert to graph
npm run mcp                 # Start MCP server (stdio)
npm run schema              # Create/update graph indexes
npm run test-connection     # Verify DB connectivity
npm test                    # Run tests (vitest)
npm run viz:dev             # Dev server (API at :4200, UI at :4201)
npm run viz                 # Production build + serve

Using with Claude

Claude Code / Claude Desktop

The global MCP server is configured in ~/.claude/settings.json. For project-specific instances, add a .mcp.json in the project root:

{
  "mcpServers": {
    "brainifai": {
      "command": "npx",
      "args": ["tsx", "--env-file=.env", "src/mcp/index.ts"],
      "cwd": "/path/to/Brainifai",
      "env": {
        "GRAPHSTORE_ON_DEMAND": "true",
        "GRAPHSTORE_READONLY": "true",
        "KUZU_DB_PATH": "/path/to/project/.brainifai/data/kuzu",
        "BRAINIFAI_INSTANCE_PATH": "/path/to/project/.brainifai"
      }
    }
  }
}

Hooks

Brainifai includes Claude Code hooks for automatic context enrichment:

PreToolUse — injects relevant KG context before Claude uses a tool
SessionStart — pulls working-memory atoms (here + global) from the engine into the session header
PostToolUse (auto-remember) — after a git commit, instructs Claude to call consolidate so the commit becomes a memory

Skills

Manual counterparts to the hooks, invoked via /<name>:

/where — show current instance + recent atoms (here + global)
/recall <cue> — search the graph by paraphrase via spreading activation
/remember — capture the current conversation as a knowledge atom

Multi-instance architecture

The system is built around a tree of instances coordinated by a global orchestrator:

Global instance (~/.brainifai/global/) — the always-on general instance. Ingests across sources, holds the engine-backed Atom/Entity/Episode graph, exposes the engine primitives via MCP
Project instances (<project>/.brainifai/<name>/) — specialized DBs and tools scoped to a project; auto-resolved from cwd
Event bus — file-based pub/sub for data.push, instance.registered, query.request/response messages
Context functions — composable, per-instance tools registered in a global registry and activated based on instance config/template
Skill generator — auto-generates Claude Code skills from an instance's active context functions
Maintenance passes — scheduled background jobs over the engine graph (tier-recompute, alias-confirm shipped; dedupe, summarize, theme-detect, aging-audit planned)

Key design decisions

All ingestion uses MERGE — safe to re-run, no duplicates
Cursors stored in graph DB — wipe DB = clean re-backfill
MCP exposes curated tools only, no raw Cypher to the LLM
Safety limits: MAX_EVIDENCE=20, MAX_TOTAL_CHARS=8000, QUERY_TIMEOUT=10s
Kuzu (embedded) — no Docker, no external DB process
OnDemand graph store for MCP/hooks — avoids write lock contention with ingestion
Each instance self-describes so the orchestrator can route without hardcoded rules
Cross-source identity resolution links the same person across Slack, GitHub, and email
All LLM calls route through @anagnole/claude-cli-wrapper (Claude CLI subscription, never the Anthropic API). ANTHROPIC_API_KEY is intentionally stripped at startup
The graph engine is reusable: each instance type plugs in a SchemaSpec (atom kinds, entity types, occurrence/association edges, resolver weights, maintenance policies) and gets writes, reads, embeddings, and maintenance for free
Researcher and project-manager instances have dedicated ingestion pipelines

Tech stack

Runtime: TypeScript (ESM), Node.js 20+
Graph DB: Kuzu (embedded, no server)
MCP: @modelcontextprotocol/sdk (stdio transport)
API: Fastify + WebSocket
Visualization: React 19, Sigma.js v3, Graphology
LLM integration: @anagnole/claude-cli-wrapper (unified provider for Claude CLI)
CLI: Commander
Testing: Vitest
Sources: Slack Web API, Octokit, tsdav (CalDAV), ClickUp REST API, Twitter/X (raw fetch)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
.claude		.claude
bin		bin
docs		docs
scripts		scripts
src		src
ui/.next/dev/types		ui/.next/dev/types
.DS_Store		.DS_Store
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
architecture.png		architecture.png
docker-compose.yml		docker-compose.yml
idea.md		idea.md
package-lock.json		package-lock.json
package.json		package.json
test-init-sequence.mts		test-init-sequence.mts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Brainifai

How it works

Architecture

Data sources

Graph model

Instance types

Setup

Prerequisites

Install

Configure sources

CLI

Run

Using with Claude

Claude Code / Claude Desktop

Hooks

Skills

Multi-instance architecture

Key design decisions

Tech stack

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Brainifai

How it works

Architecture

Data sources

Graph model

Instance types

Setup

Prerequisites

Install

Configure sources

CLI

Run

Using with Claude

Claude Code / Claude Desktop

Hooks

Skills

Multi-instance architecture

Key design decisions

Tech stack

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages