org-mind
KanishkaKrSingh/org-mind
Persistent organizational memory MCP server for Claude Code. Eliminates the context cold-start problem — one knowledge graph, every developer, every session.
Instalação
npx convez-ai KanishkaKrSingh/org-mind1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
ORG-MIND 🧠
Persistent organizational memory for Claude Code.
Instead of every developer re-generating the same context from scratch, ORG-MIND maintains a live knowledge graph of your entire engineering org — and Claude Code tool-calls it.
The Problem
Every Claude Code session starts blind. In a 50-service org with 200 engineers:
200 devs × 5 sessions/day × 80,000 tokens = 80 million tokens/day
just in context regeneration
Every developer independently asks: "What does this service own? Who's the team? What does auth-service expose? Will this schema change break anything?"
ORG-MIND answers all of that in < 100ms, once, for everyone.
How It Works
Your GitHub org
│
│ push events (webhook)
▼
┌─────────────────────────────────────────────────────┐
│ INGESTION PLANE │
│ │
│ GitHub Connector → file classifier │
│ OpenAPI Parser → endpoint nodes │
│ DB Introspector → schema nodes │
│ gRPC Parser → RPC nodes │
│ ADR Watcher → decision nodes │
│ SigNoz Connector → error pattern nodes │
└────────────────┬────────────────────────────────────┘
│ write
▼
┌─────────────────────────────────────────────────────┐
│ STORAGE PLANE │
│ │
│ Neo4j — service graph, deps, ownership │
│ Qdrant — semantic vector search │
│ Redis — L1 cache + task queue │
└────────────────┬────────────────────────────────────┘
│ query
▼
┌─────────────────────────────────────────────────────┐
│ MCP SERVER (stdio/SSE) │
│ │
│ get_service_context get_dependency_graph │
│ get_schema get_api_contracts │
│ get_adrs get_file_context │
│ get_error_patterns search_org_knowledge │
│ get_breaking_changes get_ownership │
└────────────────┬────────────────────────────────────┘
│ tool calls
▼
Claude Code (every developer's session)
A developer opens Claude Code in any repo. Without typing a single word of context, Claude already knows:
- What the service does, who owns it, which team's Slack channel
- Every service it calls and every service that calls it
- All DB tables it owns + recent schema migrations
- API contracts (with breaking change flags)
- Governing ADRs
- Live error patterns from SigNoz
The Knowledge Graph
10 services across 6 teams · 15 dependency edges · 19 DB tables · 22 API endpoints — all queryable in < 100ms
Token Savings
| Without ORG-MIND | With ORG-MIND | |
|---|---|---|
| Tokens per session | ~80,000 | ~6,000 |
| 200 devs × 5 sessions/day | 80M tokens/day | 6M tokens/day |
| Cost at $3/M tokens | $240/day | $18/day |
| Annual saving | — | ~$81,000 |
ROI: < 2 weeks. Running cost: ~$520–1,080/month.
Quick Start (5 commands)
Prerequisites
- Docker + Docker Compose
- Node.js ≥ 20
- Python 3.12+
- An OpenAI API key
# 1. Clone
git clone https://github.com/kanishkasingh-sys/org-mind.git
cd org-mind
# 2. Configure your org
cp .env.example .env # fill in NEO4J_PASSWORD + OPENAI_API_KEY
nano config/org-config.yaml # register your org + services (see below)
# 3. Start infrastructure
docker compose up -d
# 4. Initialise schema + collections
./scripts/init-neo4j.sh
./scripts/init-qdrant.sh
# 5. Build + connect to Claude Code
cd org-mind-mcp && npm install && npm run build
Then add to ~/.mcp.json:
{
"mcpServers": {
"org-mind": {
"command": "node",
"args": ["/path/to/org-mind/org-mind-mcp/dist/server.js"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_PASSWORD": "your_password",
"REDIS_URL": "redis://localhost:6379/0",
"QDRANT_URL": "http://localhost:6333",
"OPENAI_API_KEY": "sk-...",
"ORG_CONFIG_PATH": "/path/to/org-mind/config/org-config.yaml"
}
}
}
}
Open any repo in Claude Code — ORG-MIND activates automatically.
Registering Your Organization
Edit config/org-config.yaml:
orgs:
- org_id: "myorg"
display_name: "My Company"
github_org: "my-github-org"
github_webhook_secret: "${MY_WEBHOOK_SECRET}"
qdrant_collection_prefix: "myorg"
services:
- service_id: "payments-api"
repo: "my-github-org/payments-api"
language: "java"
team: "payments"
owner: "payments@mycompany.com"
databases:
- type: "postgres"
connection_env: "PAYMENTS_DB_URL"
owned_schemas: ["payments", "ledger"]
depends_on: ["auth-service", "fraud-service"]
- service_id: "auth-service"
repo: "my-github-org/auth-service"
language: "go"
team: "platform"
owner: "platform@mycompany.com"
databases: []
depends_on: []
Adding a new org — zero code changes:
- Add entry to
org-config.yaml - Add env vars to
.env ./scripts/init-qdrant.sh --org-id=neworg./scripts/register-webhook.sh --org-id=neworg --webhook-url=https://your-host/webhook/github- Restart workers:
docker compose restart celery-worker celery-beat
Service Onboarding Checklist
For full coverage, each registered service should have:
-
README.mdat repo root ← used for service summary - OpenAPI spec at
openapi.yamlordocs/openapi.yaml -
CODEOWNERSfile ← drives team ownership edges - DB migrations in
db/migrations/or FlywayV*.sqlpattern - ADRs in
docs/adr/ADR-NNN-title.md - gRPC protos in
/proto/(for gRPC services)
Architecture Deep Dive
Tri-Layer Storage
| Layer | Technology | What it stores | Latency |
|---|---|---|---|
| L1 | Redis 7 | Query result cache | < 5ms |
| L2 | Qdrant Cloud | Vector embeddings (semantic search) | < 80ms |
| L3 | Neo4j 5 | Service graph, dependencies, ownership | < 250ms |
Every tool call hits L1 first. On miss → L2+L3 in parallel → result cached for 15 min.
Smart Delta Ingestion
GitHub push → HMAC-validated webhook
→ file classifier (openapi / proto / sql / adr / code)
→ content hash vs. stored hash in Neo4j
→ only changed files re-indexed
→ Redis Stream batch queue (flush every 15 min)
→ HIGH priority queue for schema/API changes
The 10 MCP Tools
| Tool | What Claude calls it for |
|---|---|
get_service_context | Session start — full context bundle |
get_dependency_graph | Impact analysis before making changes |
get_schema | DB table layouts before writing migrations |
get_api_contracts | Endpoint signatures + breaking change flags |
get_adrs | Architecture decisions governing the service |
get_file_context | Semantic summary of the file being edited |
get_error_patterns | Live SigNoz errors during debugging |
search_org_knowledge | "How does idempotency work in our org?" |
get_breaking_changes | Breaking API/schema changes in last N days |
get_ownership | Who owns this? What's their Slack? |
Deployment (Production)
Infrastructure
org-mind/
├── docker-compose.yml # Dev: Neo4j + Redis + Qdrant + workers
└── k8s/ # Prod: Kubernetes manifests (Phase 4)
├── neo4j-statefulset.yaml
├── redis-deployment.yaml
└── workers-deployment.yaml
Recommended production topology:
- Neo4j: Dedicated VM, 4 vCPU / 16GB RAM
- Redis: 2 vCPU / 8GB RAM (also handles Celery queue)
- Qdrant: Cloud (qdrant.io) — ~$200–400/mo for 50 services
- MCP Server: 2 replicas behind a load balancer
- Workers: 3–5 Celery pods (scale by queue depth)
Security
- GitHub webhooks validated with HMAC-SHA256
- GitHub tokens never stored — used in-flight for ACL, then dropped
- All Neo4j + Redis traffic over internal network only
- Qdrant Cloud: per-org API keys
- Per-repo ACL enforced at query time (not post-filter)
Local Demo (Without a Full Org)
If you want to see the graph working without connecting a real GitHub org, use the local ingestion script:
# Point at your local repo clones
REPOS_ROOT=~/path/to/your/repos python3 scripts/ingest-local-repos.py
This reads your local files directly (no GitHub API needed) and populates the graph from:
application.properties→ service dependencies + DB schemas- SQL migrations → DB table nodes
- Spring controllers → API endpoint nodes
docs/adr/*.md→ ADR nodesREADME.md→ service summary
Then open http://localhost:7474 (Neo4j Browser) and run:
MATCH (n)-[r]->(m) RETURN n, r, m
Technology Stack
| Component | Technology | Why |
|---|---|---|
| MCP Server | TypeScript + @modelcontextprotocol/sdk | Official Anthropic SDK, strong typing |
| Connectors | Python 3.12 + FastAPI + Celery | Best ecosystem for protoc, DB clients, GitHub API |
| Graph DB | Neo4j 5.x | Native graph traversal, readable Cypher |
| Vector Store | Qdrant | Best payload filtering, sparse+dense hybrid |
| Cache + Queue | Redis 7 | Streams for batch queue, sub-ms cache |
| Embeddings | OpenAI text-embedding-3-large | Highest quality for code+prose |
| Deploy | Docker Compose (dev) → Kubernetes (prod) |
Roadmap
- Phase 1 — Foundation: GitHub connector, Neo4j graph, 2 MCP tools, ACL
- Phase 2 — Data richness: OpenAPI + gRPC + DB connectors, vector search, 10 tools
- Phase 3 — SigNoz + live errors, breaking change detection, search
- Phase 4 — SSE transport, admin dashboard, Slack alerting
- Phase 5 — CI/CD connector, auto-ADR generation, impact analysis tool
- Phase 6 — Multi-tenant SaaS mode, CLAUDE.md auto-injection per repo
Contributing
This project is structured for easy extension:
- Add a new connector: Create
ingestion/workers/myconnector_connector.py, register incelery_app.py - Add a new MCP tool: Create
org-mind-mcp/src/tools/my-tool.ts, register intools/index.ts - Add a new org: Edit
config/org-config.yaml— zero code changes
License
MIT — use freely, attribution appreciated.