brain-neural-core 1.0.1__tar.gz

brain_neural_core-1.0.1/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 brainledger-solutions
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

brain_neural_core-1.0.1/MANIFEST.in

@@ -0,0 +1,8 @@
+# Keep the source distribution as lean as the wheel: the package + essential
+# metadata ONLY (README, LICENSE, pyproject). setuptools already limits the sdist
+# to the package plus metadata; the one extra it pulls in is the top-level tests/
+# tree, which end users don't need — so drop it. Nothing internal (design, strategy,
+# deploy, .brain) is ever included by the default file finder.
+prune tests
+global-exclude *.py[cod]
+global-exclude .DS_Store

brain_neural_core-1.0.1/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: brain-neural-core
+Version: 1.0.1
+Summary: Project Brain — Engineering memory for AI-assisted teams
+Author-email: BrainLedger Solutions <brainledger.solutions@gmail.com>
+License-Expression: FSL-1.1-ALv2
+Project-URL: Homepage, https://brainledger.solutions
+Project-URL: Playground, https://try.brainledger.solutions/
+Keywords: ai,agents,engineering-memory,mcp,llm,code-context,git,developer-tools,knowledge-base
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: GitPython>=3.1.43
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: click>=8.1.7
+Requires-Dist: rich>=13.7.1
+Requires-Dist: mcp<2,>=1.29
+Provides-Extra: openai
+Requires-Dist: openai>=1.35.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.28.0; extra == "anthropic"
+Provides-Extra: google
+Requires-Dist: google-generativeai>=0.7.0; extra == "google"
+Provides-Extra: groq
+Requires-Dist: openai>=1.35.0; extra == "groq"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: all-cloud
+Requires-Dist: openai>=1.35.0; extra == "all-cloud"
+Requires-Dist: anthropic>=0.28.0; extra == "all-cloud"
+Requires-Dist: google-generativeai>=0.7.0; extra == "all-cloud"
+Provides-Extra: docs
+Requires-Dist: python-docx>=1.1.0; extra == "docs"
+Requires-Dist: pypdf>=4.0.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: openai>=1.35.0; extra == "all"
+Requires-Dist: anthropic>=0.28.0; extra == "all"
+Requires-Dist: google-generativeai>=0.7.0; extra == "all"
+Requires-Dist: python-docx>=1.1.0; extra == "all"
+Requires-Dist: pypdf>=4.0.0; extra == "all"
+Dynamic: license-file
+
+# Project Brain
+
+![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue.svg)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![Status: Beta](https://img.shields.io/badge/status-beta-orange.svg)
+![Local-first](https://img.shields.io/badge/architecture-local--first-2ea44f.svg)
+![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2.svg)
+
+**Engineering memory for AI-assisted teams.** Project Brain captures the decisions,
+constraints, and hard-won lessons in your codebase — automatically, on every push — keeps
+them in version control alongside your code, and serves them to your AI coding agents so a
+session starts with what your team already decided instead of guessing at it.
+
+It is **deterministic by default** (no LLM, API key, or network required) and
+**conflict-aware**: when new work contradicts a settled decision, Brain flags it and records
+how you resolved it.
+
+---
+
+**Try it without installing:** [try.brainledger.solutions](https://try.brainledger.solutions/)
+
+## Setup
+
+**Prerequisites:** Python 3.10+ and Git must be on your PATH.
+
+### Quick path — one command after install
+
+```bash
+# 1. install
+pip install brain-neural-core
+
+# 2. wire repos, seed memory, and verify in one go
+brain setup
+```
+
+`brain setup` walks you through each repo interactively, runs `brain init` and
+`brain bootstrap` for each one, then performs the step-6 `brain doctor` check.
+Steps 3 and 4 below (editor restart and approval) are still yours.
+
+### Manual steps — if you prefer to run each piece yourself
+
+Six steps, once per repository. Run them in this order.
+
+```bash
+# 1. install
+pip install brain-neural-core
+
+# 2. wire this repo — git hooks + MCP config for your editor
+cd your-repo
+brain init
+
+# 3. seed memory from the history you already have
+brain bootstrap
+```
+
+**4. Restart VS Code** (or whichever editor you use — quit and reopen it).
+
+An MCP server is only discovered when a session starts, so Brain is invisible to any editor
+window that was already open. **This is the most common reason an agent reports no Brain tools.**
+
+**5. Approve the server when your editor asks.** An editor will not launch a local program just
+because a config file says so. In Claude Code, accept the *trust this project* prompt; in Cursor,
+Windsurf or Cline, enable `project-brain` in the MCP settings if it shows as disabled.
+
+```bash
+# 6. verify — this performs a real MCP handshake, it does not just check for files
+brain doctor
+```
+
+Expect `MCP handshake  10 tool(s), 2 prompt(s)`. If you see that, setup is done.
+
+From here, keep using Git as before: `git push` captures new memory, `git pull` captures rationale
+from merged pull requests, and your agent is served the relevant memory before it edits a file.
+
+*Optional extras, not needed for the above:* `pip install "brain-neural-core[openai]"` — or
+`[anthropic]`, `[google]`, `[groq]` — enables the optional LLM enrichment pass (`brain init --llm`).
+`[docs]` reads `.docx` / `.pdf`, which are picked up by capture on push, not by `brain bootstrap`.
+
+## How it works
+
+1. **Capture.** On every push/merge, Brain reads your commits and code and records structured
+   engineering memory across seven kinds:
+
+   | Kind | What it captures |
+   |---|---|
+   | **Decision** | why it was built this way |
+   | **Constraint** | a limit or invariant the code must hold |
+   | **Business rule** | a domain rule the code must reflect |
+   | **Historical failure** | something that broke before — so it isn't repeated |
+   | **Trade-off** | what was exchanged for what |
+   | **Intent** | what a feature is meant to do |
+   | **Technical debt** | a `TODO`/`FIXME` the team acknowledged and deferred |
+
+   The first six are **rules**: they go into `AGENTS.md` and are served to your agent before it
+   edits a file. Technical debt is recorded, exported and counted, but deliberately kept out of
+   both — it is acknowledged-but-deferred work, not a rule to obey.
+
+   It runs locally and deterministically — nothing leaves your machine.
+
+2. **Store.** Memory lives in version control (`AGENTS.md` + a `.brain/` folder), so it travels
+   with the repository and merges cleanly across your team.
+
+3. **Serve.** Brain ships an **MCP server** that hands the relevant memory to your AI agent
+   *before* it edits a file — so the agent respects your prior decisions instead of relitigating
+   them.
+
+4. **Stay conflict-aware.** When a newly-captured decision contradicts a settled one, Brain
+   surfaces it — in your agent's chat and in `brain review`. Accepting the new one **supersedes**
+   the old: the resolution is recorded (what replaced what, when, and by whom), and the retired
+   decision is kept as history but no longer served.
+
+**Deterministic by default.** Capture, conflict detection, and serving all run with no LLM, key,
+or network. An **optional** enrichment pass (bring your own key — local via
+[Ollama](https://ollama.com), or a cloud provider) adds deeper, inferred memory; enable it with
+`brain init --llm`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `brain init` | Set up Brain in the current repo (capture + AI-tool config). One-time. |
+| `brain setup` | Check the machine, wire one or more repos, and verify an agent can reach Brain. |
+| `brain bootstrap` | Seed memory from your existing history. One-time deep scan. |
+| `brain status` | What Brain knows about this repo, at a glance. |
+| `brain review` | Review proposed memory — accept (and supersede conflicts) or reject. |
+| `brain search <words>` | Search your memory by keyword — the claim, its rationale, its file. |
+| `brain value` | Whether Brain has actually changed anything for you, and where it hasn't. |
+| `brain context --file <path>` | Show the memory relevant to a file (what your agent receives). |
+| `brain view` | Project the memory into a risk & knowledge report, a one-page brief, or a team-adoption rollup. |
+| `brain pending` | Show memory queued for the next push, before it is shared. |
+| `brain add` | Manually record a decision, rule, or constraint. |
+| `brain forget <text-or-id>` | Remove a captured item that is wrong, and stop it coming back. |
+| `brain export` | Export captured memory to a shareable text file. |
+| `brain verify` | Retire memory whose source file is gone, report stale items, and rebuild `AGENTS.md` if it has drifted from `.brain/memory/`. |
+| `brain doctor` | Verify the setup and diagnose issues. |
+| `brain uninstall` | Remove Brain's wiring from a repo (memory is kept unless you ask). |
+
+Capture on `git push` / `git pull` is automatic after `brain init` — you rarely run it by hand.
+Run `brain --help` for the full list.
+
+## Connect your AI tool (MCP)
+
+`brain init` writes the config for **Cursor, Claude Code, Windsurf and Cline** (step 2 above);
+any MCP-capable client can point at the bundled `brain-mcp-server`. Steps 4 and 5 of *Setup* —
+restart the editor, approve the server — are the parts that cannot be automated from here.
+
+Per-editor detail for step 5:
+
+- **Claude Code** — reads `.mcp.json` at the repo root and prompts you to **trust the project**
+  the first time you open it. Accept it, then run `/mcp`; `project-brain` should be listed. If it
+  is never offered, register it at user scope instead:
+
+  ```bash
+  claude mcp add project-brain brain-mcp-server -e "BRAIN_REPO_ROOT=/path/to/your-repo"
+  claude mcp list          # project-brain should appear
+  ```
+
+- **Cursor / Windsurf / Cline** — open the MCP settings and enable `project-brain` if it shows as
+  disabled or pending. `brain init` wrote `.cursor/mcp.json`, `.windsurf/mcp.json` or
+  `.cline/mcp_settings.json`.
+
+### Two commands you can run inside the chat
+
+Once the server is connected, your editor lists Brain's prompts alongside its own — in Claude
+Code they appear as `/mcp__project-brain__…`:
+
+| prompt | what it does |
+|---|---|
+| **`value`** | Reports what Brain has actually changed in this repo, in the chat. Same figures as `brain value`. |
+| **`why`** (`file`) | Explains why a file is the way it is, using **only** recorded memory — and says so plainly where nothing was recorded, rather than inferring a rationale from the code. |
+
+Like tools, prompts are fixed when a session starts, so they appear after the next restart.
+
+### After a reboot, or an OS update
+
+**Nothing to restart.** The MCP server is not a background service — your IDE launches
+`brain-mcp-server` on demand over stdio and it exits with the session. A reboot leaves no
+state to recover, and the first agent session afterwards starts it fresh.
+
+What *does* break the link is anything that **moves the executable**, because the config
+records its absolute path: `pipx reinstall`, a Python minor upgrade, switching between pip and
+pipx, or recreating a venv. Symptom: the agent has no Brain tools, and `brain doctor` reports
+the handshake failing.
+
+```bash
+brain init          # re-stamps the paths in this repo
+brain doctor        # confirm the handshake passes again
+```
+
+Git hooks are stamped the same way, so re-running `brain init` after any environment change
+fixes capture and MCP together.
+
+## Is Brain actually capturing?
+
+A hook file existing is not a hook running, so Brain records a heartbeat each time capture
+runs and reports it plainly:
+
+```bash
+brain doctor        # per repo, with the reason
+brain status        # push count and last capture date
+```
+
+| what you see | what it means |
+|---|---|
+| `capture is running` | the hook ran at the current commit — working |
+| `capture is STALE` | it ran before, but commits have landed since without capture |
+| `capture never ran here` | no heartbeat at all — expected in a fresh clone, since **git hooks are never cloned** |
+
+`brain status` also reports the other half — whether anything has actually *read* the memory:
+
+```
+Served to agents
+  Retrievals (7 days):      24
+  Last retrieval:           2026-08-05 09:12 UTC
+  Most used:                get_context x18, search_memory x4
+```
+
+`none recorded on this machine` means either no agent has queried Brain yet, or MCP isn't
+reachable — `brain doctor` performs a real handshake and tells you which. This reads the
+local, per-developer log, so it reflects *your* machine, not the team's.
+
+That last one is the case people miss: cloning a Brain-enabled repo brings the memory but not
+the hooks. Run `brain init` in the clone, make a commit and push, and the state moves to
+`capture is running`.
+
+For a repo where capture must not silently stop, `brain setup --ci` installs a GitHub Actions
+workflow that reports when memory has not been updated alongside a change.
+
+## Is it worth keeping?
+
+```bash
+brain value
+```
+
+Counts the times Brain **changed an outcome** — a rule that blocks, an approach already
+rejected in this repo, a contradiction caught before it landed — and keeps those apart from
+raw retrieval counts, which only prove a tool ran.
+
+```
+Did it change anything?
+  ✓  Changed the outcome           9 time(s)
+  Blocking rules supplied:      14
+  Rejected approaches raised:    3
+  Contradictions caught:         2
+
+Activity  ·  context, not value
+  Agent retrievals (30d):       12
+  ...
+
+Memory
+  Items:                        58
+  Carrying a rationale:          6 of 58 (10%) - the WHY an agent cannot re-derive
+```
+
+That last figure is usually low, and this sample is not flattering it: across our 58-repository
+corpus only about **2%** of captured items carry a rationale. Most memory records *what* a rule is,
+not why it exists — which is a real limitation, and one `brain value` is designed to show you
+rather than hide.
+
+It will also tell you when the answer is unflattering. **`Read, but not steering`** means your
+agent is pulling memory but none of it was consequential — usually because the captured items
+restate the code instead of recording a *why*. **`No evidence yet`** means nothing has queried
+Brain at all, which is most often MCP not being authorised in your editor; `brain doctor`
+performs a real handshake and tells you which.
+
+## Working as a team
+
+Captured **memory collates by itself** — `AGENTS.md` and `.brain/memory/` are committed, so
+everyone on the repo shares it through normal `git pull` / `git push`, and `brain init`
+registers merge drivers that union concurrent capture instead of conflicting.
+
+**Each teammate still runs the whole of *Setup* once per clone** — all six steps, including the
+editor restart. Git does not clone hooks, and MCP config is per-machine, so a fresh clone captures
+nothing and serves nothing until they do. They can skip step 3 (`brain bootstrap`); the memory is
+already committed.
+
+To see whether it is actually being used:
+
+```bash
+brain view --lens team
+```
+
+```
+Team totals
+  Developers reporting:    4
+  Memory contributed:      82
+  Conflicts caught:        4
+  Agent retrievals:        267
+
+By developer
+  developer               contributed  conflicts  retrievals   last active
+  Arjun Sharma                     58          3         142    2026-08-05
+  Priya Nair                        9          0           0    2026-07-30
+  !  not retrieving   1 developer(s) contribute memory but never read it
+```
+
+Each developer's machine writes one shard to `.brain/metrics/<name>.json` on push. One file
+per person means shards never merge-conflict. They hold **counts and a date only** — never
+your queries, file paths, or per-call times — and a developer showing contributions but zero
+retrievals almost always has MCP unauthorised in their editor, which `brain doctor` on that
+machine will confirm.
+
+## Status
+
+**Beta.** The deterministic capture path, MCP serving and conflict handling are in daily use and
+covered by over 1,300 tests, run on Windows and Linux.
+
+Every release is regression-tested against a 58-repository corpus, and extraction quality is
+checked by hand-labelling what Brain captured from repositories held out from development. On the
+most recent of those, **86–90% of captured items were judged correct** by a reviewer who did not
+write the extraction rules. That is a small sample, so treat it as indicative rather than precise;
+how much of a repository's memory Brain *finds* is not something we have measured.
+
+Extraction is not perfect — expect to prune the occasional item with `brain review` /
+`brain forget`, and please report anything that looks wrong.
+
+Brain is built for working codebases. Pointed at a tutorial or textbook repository, it will mine
+the subject matter being taught as though it were the project's own decisions.
+
+**In progress:** richer rationale on captured items, and better handling of plain configuration
+values. Memory is plain JSON in your repo, so nothing is ever locked in.
+
+## License
+
+Source-available under **FSL-1.1-Apache-2.0** — free for internal and most uses. The full text
+ships as `LICENSE.md` inside the package.
+
+*(PyPI and `pip show` display this licence as `FSL-1.1-ALv2`. Same licence, two registries: the
+Functional Source License names itself `FSL-1.1-Apache-2.0`, while `FSL-1.1-ALv2` is its SPDX
+identifier, and Python package metadata must use SPDX.)*