{"id":51293079,"url":"https://github.com/vbcherepanov/braincore","last_synced_at":"2026-06-30T12:03:10.511Z","repository":{"id":356751748,"uuid":"1233781045","full_name":"vbcherepanov/braincore","owner":"vbcherepanov","description":"Local-first cognitive memory for AI coding agents — attention, decision graph, and the right to say \"I don't know.\" MCP-native, plugs into Claude Code, Codex, Cursor and Cline.","archived":false,"fork":false,"pushed_at":"2026-05-19T08:07:29.000Z","size":9,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T10:54:37.321Z","etag":null,"topics":["ai-agents","ai-memory","anti-hallucination","claude-code","cline","codex","cursor","decision-graph","go","golang","knowledge-graph","llm-memory","local-first","mcp","mcp-server","ollama","pgvector","rag"],"latest_commit_sha":null,"homepage":"https://getbraincore.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vbcherepanov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T10:55:23.000Z","updated_at":"2026-05-19T08:07:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vbcherepanov/braincore","commit_stats":null,"previous_names":["vbcherepanov/braincore"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vbcherepanov/braincore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbcherepanov%2Fbraincore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbcherepanov%2Fbraincore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbcherepanov%2Fbraincore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbcherepanov%2Fbraincore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vbcherepanov","download_url":"https://codeload.github.com/vbcherepanov/braincore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbcherepanov%2Fbraincore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34965643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-memory","anti-hallucination","claude-code","cline","codex","cursor","decision-graph","go","golang","knowledge-graph","llm-memory","local-first","mcp","mcp-server","ollama","pgvector","rag"],"created_at":"2026-06-30T12:03:09.602Z","updated_at":"2026-06-30T12:03:10.466Z","avatar_url":"https://github.com/vbcherepanov.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eBrainCore\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe memory layer that lets your AI coding agent say \"I don't know.\"\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eLocal-first · 0.95 R@5 · 4ms p95 retrieval · Strict abstain by design\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://getbraincore.com\"\u003eWebsite\u003c/a\u003e ·\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/vbcherepanov/total-agent-memory\"\u003eOpen-source companion\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://getbraincore.com\"\u003e\u003cimg alt=\"Website\" src=\"https://img.shields.io/badge/site-getbraincore.com-10b981?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Status\" src=\"https://img.shields.io/badge/status-Private%20Beta-blueviolet?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Made with Go\" src=\"https://img.shields.io/badge/Go-1.25-00ADD8?logo=go\u0026style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"MCP\" src=\"https://img.shields.io/badge/MCP-stdio-1f6feb?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://x.com/BestProgerVR\"\u003e\u003cimg alt=\"X / Twitter\" src=\"https://img.shields.io/badge/follow-%40BestProgerVR-1DA1F2?logo=x\u0026style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why this exists\n\nYou ship code with an AI coding agent. You watch it confidently rewrite a function based on a chunk that belongs to a branch deleted two months ago. Cosine similarity high. Top-1 retrieval. Honest stitch into the prompt. Patch against code from a different reality.\n\nThat's not memory failing. That's **search masquerading as memory** — RAG with cosine instead of BM25.\n\n**BrainCore is the layer that closes that gap.** Every fact your agent uses to generate code passes through a strict-mode gate before it lands in the prompt — and if no fact survives, the agent says *\"I don't know\"* instead of inventing one.\n\n---\n\n## What BrainCore actually does\n\nBrainCore is a **local-first cognitive memory** that sits between your IDE / coding agent and your codebase. Every fact your agent uses to generate code passes through a **strict-mode gate** before it lands in the prompt — and if no fact survives, the agent says *\"I don't know\"* instead of inventing one.\n\n```mermaid\nflowchart LR\n    A[Your AI agent\u003cbr/\u003eClaude Code · Codex · Cursor] --\u003e|MCP stdio| B[BrainCore]\n    B --\u003e C[Atomic Knowledge Units\u003cbr/\u003ew/ lifecycle + provenance]\n    B --\u003e D[Decision Graph\u003cbr/\u003eproblem → choice → outcome]\n    B --\u003e E[Source-Code Truth\u003cbr/\u003eAST · go.mod · package.json]\n    C \u0026 D \u0026 E --\u003e|gate| F{Strict Mode}\n    F --\u003e|all pass| G[Trusted context\u003cbr/\u003einjected into prompt]\n    F --\u003e|any fail| H[abstain → brain task\u003cbr/\u003e'I need evidence for X']\n    style F fill:#10b981,stroke:#0a8060,color:#fff\n    style H fill:#ef4444,stroke:#991b1b,color:#fff\n    style G fill:#1f6feb,stroke:#0d4ba0,color:#fff\n```\n\nResult: an agent that *refuses* to write code based on a deleted file, a deprecated decision, or a hypothetical fact you never confirmed.\n\n---\n\n## The headline numbers\n\n\u003ctable\u003e\n\u003ctr\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003e0.95 R@5\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eretrieval recall\u003cbr/\u003eat gate threshold 0.85\u003c/sub\u003e\u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003e4 ms p95\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eretrieval latency\u003cbr/\u003eacross atomic + graph\u003c/sub\u003e\u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003e0%\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003econfidently-wrong\u003cbr/\u003eactions in bench\u003c/sub\u003e\u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003e30%\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003ehonest abstain rate\u003cbr/\u003e(traded for the 0% above)\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003e11/11\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003elegacy migration tests\u003cbr/\u003egreen\u003c/sub\u003e\u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003eLocal\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eyour code never leaves\u003cbr/\u003ethe box, period\u003c/sub\u003e\u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003eMCP\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eplugs into Claude Code,\u003cbr/\u003eCodex, Cursor, Cline\u003c/sub\u003e\u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\u003cstrong\u003eApache-2.0\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eopen companion:\u003cbr/\u003etotal-agent-memory\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Cognitive functions BrainCore models\n\nA \"memory tool\" stores text. A **cognitive layer** models how an agent should\n*think* about that text. BrainCore implements the cognitive functions that\nturn raw retrieval into a brain that can reason — and stay silent when it has to.\n\n| Cognitive function | What BrainCore implements | What's broken without it |\n|---|---|---|\n| **Memory** | Atomic knowledge units with lifecycle: `staging → working → consolidated → archived` | Stale chunks parade as current truth |\n| **Attention** | Strict-mode gate filters by source, confidence, temporal validity, contradiction | Top-k cosine returns everything, agent reads garbage |\n| **Reasoning** | Causal decision chains (`problem → alternatives → decision → reasoning → outcome`) | Three flat fragments, model invents the missing logic |\n| **Perception of code** | AST-based identity (Tree-sitter, 9 langs) — \"this symbol\", not \"this string\" | Patches written against deleted branches |\n| **Negative learning** | Failures, regressions, rejected decisions are first-class entities | Agent ships the same bug it shipped 3 months ago |\n| **Metacognition** | Self-model: competencies, blind spots, brain-tasks backlog | Agent doesn't know what it doesn't know |\n| **Abstain** | \"I don't know\" as a first-class outcome, with an explicit reason | Confident hallucinations indistinguishable from real answers |\n\nThese map 1-to-1 onto the [seven architectural principles](#the-seven-principles-braincore-is-built-on) below — every cognitive function has a Postgres schema and a Go module behind it, not a prompt-engineering trick.\n\n---\n\n## The seven principles BrainCore is built on\n\nThe full deep-dive is in [Part 2 of the series](#articles). Headlines:\n\n| # | Principle | What it kills |\n|---|-----------|---------------|\n| 1 | **Atomic Knowledge Units with lifecycle** — `staging → working → consolidated → archived` | Stale chunks parading as current truth |\n| 2 | **Strict Mode + right to abstain** — no fact → no answer | \"Confident hallucinations\" disguised as accuracy |\n| 3 | **Causal decision chains** — `problem → alternatives → decision → reasoning → outcome` | Decisions reduced to three flat fragments by the chunker |\n| 4 | **AST-based code identity** — symbols, not text | Patches written against deleted branches |\n| 5 | **Internal git versioning of memory** — every fact has a commit | \"When did we change our mind?\" being unanswerable |\n| 6 | **Negative memory + rule engine** — what *failed* is first-class | Repeating the same regression you fixed three months ago |\n| 7 | **Self-model** — competencies, blind spots, brain-tasks backlog | Agent that pretends to know what it doesn't |\n\n*Each principle in BrainCore corresponds to an explicit Postgres schema + a Go module — not a prompt-engineering trick.*\n\n---\n\n## How a query flows through\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant Agent as AI Agent (Claude/Codex/Cursor)\n    participant MCP as braincore-mcp\n    participant API as BrainCore API\n    participant Mem as Atomic + Graph + Code\n    participant Gate as Strict Mode\n\n    Agent-\u003e\u003eMCP: memory_recall(\"why did we pick JWT?\")\n    MCP-\u003e\u003eAPI: POST /v1/recall\n    API-\u003e\u003eMem: parallel fan-out (semantic + graph + AST)\n    Mem--\u003e\u003eAPI: candidate facts (10ms)\n    API-\u003e\u003eGate: source? confidence? temporal? contradiction?\n    Gate--\u003e\u003eAPI: 4 passed, 6 dropped (1 stale, 2 unsourced, 3 contradicted)\n    API--\u003e\u003eMCP: { facts: [...], abstained_for: [...] }\n    MCP--\u003e\u003eAgent: structured context, NOT raw chunks\n    Note over Agent,Gate: If 0 facts pass — abstain + brain task,\u003cbr/\u003eNOT a confident hallucination.\n```\n\nThe agent receives **decisions and atomic facts**, not chunks. The structure carries the metadata your prompt needs to *reason*, not just *recite*.\n\n---\n\n## Versus other memory tools\n\n|  | BrainCore | Mem0 / Letta / Zep | Generic vector RAG (Qdrant + bge) |\n|---|---|---|---|\n| **Local-first by default** | Yes — your code never leaves the box | Hybrid / cloud-first | Self-host or cloud |\n| **Strict abstain mechanism** | Yes — first-class `abstain` outcome | No — always returns top-k | No — always returns top-k |\n| **Causal decision chains** | Yes — explicit schema | Partial / flat | No |\n| **Negative memory (failures)** | Yes — rule engine | No | No |\n| **AST-based code identity** | Yes — Tree-sitter + symbols | No | No |\n| **Self-model + brain tasks** | Yes — backlog of unresolved Qs | No | No |\n| **Privacy-conscious deploy** | Single Go binary, native Ollama, optional DeepSeek fallback | Cloud-native | DIY |\n| **MCP integration** | First-class, ships `braincore-mcp` | Varies | Bring-your-own |\n\nWe don't claim to have invented any single principle. We claim that *all seven have to work in one system at the same time* — and that **a system where only five of seven actually work continues to lie to the user with a confident face**. There's only one way to see this — try assembling all seven into one codebase and watch what happens. That codebase is BrainCore.\n\n---\n\n## Architecture at a glance\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  Your machine — local-first by default                          │\n│                                                                 │\n│   ┌────────────┐    ┌────────────────────────────────────────┐  │\n│   │ Claude Code│    │           BrainCore Daemon            │  │\n│   │ Codex CLI  │MCP │                                       │  │\n│   │ Cursor     │◀──▶│  ┌─────────┐  ┌─────────┐  ┌────────┐ │  │\n│   │ Cline      │stdio│  │ API     │  │ Worker  │  │ Brain  │ │  │\n│   └────────────┘    │  │ :8765   │  │ NATS    │  │ Events │ │  │\n│                     │  └────┬────┘  └────┬────┘  └───┬────┘ │  │\n│                     │       │            │           │      │  │\n│                     │  ┌────▼────────────▼───────────▼────┐ │  │\n│                     │  │  Postgres 18 + pgvector + RLS    │ │  │\n│                     │  │  Redis 7  ·  NATS 2 JetStream    │ │  │\n│                     │  └─────────────┬────────────────────┘ │  │\n│                     │                │                      │  │\n│                     │  ┌─────────────▼──────────────────┐   │  │\n│                     │  │ Ollama (host) — bge-m3 1024d   │   │  │\n│                     │  │            qwen2.5-coder:7b    │   │  │\n│                     │  │   (DeepSeek cloud fallback,    │   │  │\n│                     │  │    per-tenant key, encrypted)  │   │  │\n│                     │  └────────────────────────────────┘   │  │\n│                     └───────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n**Stack:** Go 1.25 · Postgres 18 (pgvector) · Redis 7 · NATS 2 JetStream · Ollama (bge-m3 + qwen2.5-coder:7b) · Next.js dashboard. Six binaries, all built from one repo: `braincore-saas`, `worker`, `migrate`, `seed-demo`, `braincore-mcp`, plus the `install.sh` MCP wiring.\n\n---\n\n## Quick start\n\n### Option A — Cloud (Private Beta)\n\nBrainCore is currently in **Private Beta**, onboarding design partners by invitation only.\n\n1. Visit [getbraincore.com](https://getbraincore.com) and request a seat — describe your stack and one painful AI bug you'd want the brain to catch.\n2. We send back a signed install link + API key.\n3. Install the MCP wrapper, restart your IDE, ship.\n\n### Option B — Open-source companion\n\nThe local-only memory engine is open-sourced as **[`total-agent-memory`](https://github.com/vbcherepanov/total-agent-memory)** (Apache-2.0). Same atomic-knowledge / strict-mode / decision-graph core, minus the multi-tenant SaaS layer and the hosted MCP relay.\n\n---\n\n## What this is *not*\n\n- **Not a vector DB.** We use pgvector for one of seven retrieval layers; cosine similarity is a feature, not the product.\n- **Not a RAG framework.** RAG is Ctrl+F with embeddings. We treat it as a *primitive*, not a model.\n- **Not a chatbot.** BrainCore doesn't generate answers. It *gates* the facts the answer is grounded in.\n- **Not a cloud-only SaaS.** Local-first is the default. Your code never leaves the machine unless you explicitly opt into a cloud LLM fallback.\n\n---\n\n## FAQ\n\n**Does BrainCore replace my existing AI agent?**\nNo. It plugs in via MCP — your agent stays Claude Code / Codex / Cursor / Cline. BrainCore is the layer that decides *what facts the agent is allowed to see*.\n\n**Will my code be sent to a cloud?**\nOnly if you explicitly enable the DeepSeek fallback for embeddings/chat. Default is fully local Ollama (bge-m3 + qwen2.5-coder:7b on your hardware). The dashboard, the Postgres, the NATS — all on your box.\n\n**What's the difference between BrainCore and `total-agent-memory`?**\n`total-agent-memory` is the open-source single-tenant core. **BrainCore** adds: multi-tenant SaaS layer, design-partner onboarding, hosted MCP relay, billing, RLS hardening, audit log. Same memory model, different operational story.\n\n**Will it work with my agent stack?**\nIf your agent speaks MCP stdio — yes. Verified: Claude Code, Codex CLI, Cursor, Cline (VS Code). Coming: Continue, Gemini CLI.\n\n**Why \"BrainCore\" and not \"AntivirusForAI\"?**\nThe marketing positioning evolved. The internal moat is anti-hallucination via 8-layer factcheck (the 8th layer is *grounding against your real source code* — not against a vector index of comments about that code). The product name kept the cognitive metaphor; the value prop is \"your agent finally gets to admit it doesn't know.\"\n\n**Can I self-host the full SaaS stack?**\nTalk to us — [hi@getbraincore.com](mailto:hi@getbraincore.com). Self-hosted plans land after Private Beta.\n\n**Is the codebase open?**\nThe companion `total-agent-memory` is Apache-2.0 today. The full SaaS stack opens progressively as we exit Private Beta.\n\n---\n\n## Roadmap\n\n- [x] Atomic Knowledge Units with full lifecycle\n- [x] Strict-mode gate with explicit abstain\n- [x] Causal decision-graph schema\n- [x] AST-based code identity (Tree-sitter, 9 languages)\n- [x] MCP stdio integration (Claude Code, Codex, Cursor, Cline)\n- [x] Native Ollama + DeepSeek fallback\n- [x] Multi-tenant Postgres with RLS + per-tenant API keys\n- [ ] **Public Beta** — open signup at [getbraincore.com](https://getbraincore.com) (Q3 2026)\n- [ ] **VS Code extension** — surface brain tasks in the editor sidebar\n- [ ] **GitHub App** — block PRs that contradict committed decisions\n- [ ] **Browser-side agent** — same brain across IDE + ChatGPT/Claude.ai\n- [ ] **On-prem k8s helm chart** — Enterprise tier\n\n---\n\n## Founder\n\nBuilt by [**Vitalii Cherepanov**](https://www.linkedin.com/in/progerinvr/) — 18 years of senior backend, 3 years debugging AI agents in production.\n\n- [LinkedIn](https://www.linkedin.com/in/progerinvr/) — engineering posts, weekly\n- [X / @BestProgerVR](https://x.com/BestProgerVR) — short takes on AI memory\n- [GitHub / @vbcherepanov](https://github.com/vbcherepanov) — open-source companion + side projects\n- [hi@getbraincore.com](mailto:hi@getbraincore.com) — design-partner intake\n\n---\n\n## Talk to us\n\nIf you've ever shipped a patch your AI wrote against deleted code — we're building this for you.\n\n- **Private Beta intake:** [getbraincore.com](https://getbraincore.com) → \"Become a design partner\"\n- **Email:** [hi@getbraincore.com](mailto:hi@getbraincore.com)\n- **Issues / feature requests:** GitHub Issues on this repo\n- **Live demo / 30-min call:** book via the website\n\n\u003e *\"A good AI agent isn't the one that always answers. It's the one that never confidently does the wrong thing.\"*\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://getbraincore.com\"\u003e\n    \u003cimg alt=\"getbraincore.com\" src=\"https://img.shields.io/badge/getbraincore.com-Private%20Beta-10b981?style=for-the-badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvbcherepanov%2Fbraincore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvbcherepanov%2Fbraincore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvbcherepanov%2Fbraincore/lists"}