convez.ai
MCP Server
KanishkaKrSingh

org-mind

KanishkaKrSingh/org-mind

Ver no GitHub
InicialPluginScore · de 0 a 100

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-mind

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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-MINDWith ORG-MIND
Tokens per session~80,000~6,000
200 devs × 5 sessions/day80M tokens/day6M 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:

  1. Add entry to org-config.yaml
  2. Add env vars to .env
  3. ./scripts/init-qdrant.sh --org-id=neworg
  4. ./scripts/register-webhook.sh --org-id=neworg --webhook-url=https://your-host/webhook/github
  5. Restart workers: docker compose restart celery-worker celery-beat

Service Onboarding Checklist

For full coverage, each registered service should have:

  • README.md at repo root ← used for service summary
  • OpenAPI spec at openapi.yaml or docs/openapi.yaml
  • CODEOWNERS file ← drives team ownership edges
  • DB migrations in db/migrations/ or Flyway V*.sql pattern
  • ADRs in docs/adr/ADR-NNN-title.md
  • gRPC protos in /proto/ (for gRPC services)

Architecture Deep Dive

Tri-Layer Storage

LayerTechnologyWhat it storesLatency
L1Redis 7Query result cache< 5ms
L2Qdrant CloudVector embeddings (semantic search)< 80ms
L3Neo4j 5Service 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

ToolWhat Claude calls it for
get_service_contextSession start — full context bundle
get_dependency_graphImpact analysis before making changes
get_schemaDB table layouts before writing migrations
get_api_contractsEndpoint signatures + breaking change flags
get_adrsArchitecture decisions governing the service
get_file_contextSemantic summary of the file being edited
get_error_patternsLive SigNoz errors during debugging
search_org_knowledge"How does idempotency work in our org?"
get_breaking_changesBreaking API/schema changes in last N days
get_ownershipWho 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 nodes
  • README.md → service summary

Then open http://localhost:7474 (Neo4j Browser) and run:

MATCH (n)-[r]->(m) RETURN n, r, m

Technology Stack

ComponentTechnologyWhy
MCP ServerTypeScript + @modelcontextprotocol/sdkOfficial Anthropic SDK, strong typing
ConnectorsPython 3.12 + FastAPI + CeleryBest ecosystem for protoc, DB clients, GitHub API
Graph DBNeo4j 5.xNative graph traversal, readable Cypher
Vector StoreQdrantBest payload filtering, sparse+dense hybrid
Cache + QueueRedis 7Streams for batch queue, sub-ms cache
EmbeddingsOpenAI text-embedding-3-largeHighest quality for code+prose
DeployDocker 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 in celery_app.py
  • Add a new MCP tool: Create org-mind-mcp/src/tools/my-tool.ts, register in tools/index.ts
  • Add a new org: Edit config/org-config.yaml — zero code changes

License

MIT — use freely, attribution appreciated.


Ver o original no GitHub

Bom para

Relacionados