@andespindola/brainlink 0.1.0-alpha.0

package/AGENTS.md

@@ -0,0 +1,142 @@
+# Brainlink Agent Guide
+
+This file tells coding agents and AI assistants how to use this repository.
+
+## Project Purpose
+
+Brainlink is a local-first knowledge memory for agents.
+
+It reads a Markdown vault, extracts `[[wiki links]]` and `#tags`, builds a local SQLite full-text index, and returns compact context packages that agents can inject into prompts.
+
+## Source Of Truth
+
+Markdown files are the source of truth.
+
+The SQLite database at `.brainlink/brainlink.db` is a derived index. It can be deleted and rebuilt with:
+
+```bash
+npm run dev -- index --vault ./vault
+```
+
+Do not store permanent knowledge only in SQLite.
+
+## Agent Workflow
+
+Use this loop when using Brainlink as memory:
+
+1. Write durable knowledge into Markdown notes.
+2. Link related notes with `[[Note Title]]`.
+3. Add explicit `#tags` for retrieval.
+4. Run `index` after writes.
+5. Run `context "<task or question>"` before answering.
+6. Use the returned sources as grounded context.
+
+## Commands
+
+```bash
+npm install
+npm run build
+npm run test
+npm run check
+```
+
+Create and query a vault:
+
+```bash
+npm run dev -- init ./vault
+npm run dev -- add "Architecture" --vault ./vault --content "Markdown is the source of truth. #architecture"
+npm run dev -- index --vault ./vault
+npm run dev -- context "what architecture decisions exist?" --vault ./vault
+npm run dev -- context "what architecture decisions exist?" --vault ./vault --json
+```
+
+Inspect graph relationships:
+
+```bash
+npm run dev -- links --vault ./vault
+npm run dev -- backlinks "Architecture" --vault ./vault
+```
+
+Start the local graph UI:
+
+```bash
+npm run dev -- server --vault ./vault --port 4321
+```
+
+The server reindexes by default and exposes:
+
+```txt
+http://127.0.0.1:4321/
+http://127.0.0.1:4321/api/graph
+```
+
+Use watch mode while editing notes:
+
+```bash
+npm run dev -- server --vault ./vault --watch
+npm run dev -- watch --vault ./vault
+```
+
+Start MCP over stdio:
+
+```bash
+npm run dev -- mcp
+```
+
+Automation-facing CLI commands support `--json`. When invoking through `npm`, use `npm run --silent dev -- ...` so stdout remains valid JSON.
+
+Vault health commands:
+
+```bash
+npm run dev -- stats --vault ./vault
+npm run dev -- broken-links --vault ./vault
+npm run dev -- orphans --vault ./vault
+npm run dev -- validate --vault ./vault
+npm run dev -- doctor --vault ./vault
+```
+
+## Implementation Boundaries
+
+- Keep domain rules in `src/domain`.
+- Keep use cases in `src/application`.
+- Keep filesystem and SQLite details in `src/infrastructure`.
+- Keep CLI concerns in `src/cli`.
+- Prefer pure functions for parsing, ranking, formatting, and transformation.
+- Do not make SQLite the canonical storage layer.
+- Do not add comments with emojis.
+- Keep JSON output backwards compatible where possible.
+
+## Expected Context Output
+
+The `context` command returns Markdown:
+
+```md
+# Brainlink Context
+Query: user question
+
+## 1. Note Title
+Source: note.md
+Tags: #tag
+Score: 0.000
+
+Relevant chunk content
+```
+
+Agents should treat `Source` as citation metadata and preserve it when reasoning about project memory.
+
+## Verification Before Handoff
+
+Run:
+
+```bash
+npm run check
+```
+
+For CLI behavior, also run a smoke flow with a temporary vault:
+
+```bash
+npm run dev -- init .tmp-vault
+npm run dev -- add "Architecture" --vault .tmp-vault --content "Markdown source of truth. #architecture"
+npm run dev -- index --vault .tmp-vault
+npm run dev -- context "architecture" --vault .tmp-vault
+```

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0-alpha.0
+
+- Added local-first Markdown vault indexing.
+- Added SQLite FTS, local semantic retrieval, wiki links, backlinks and graph retrieval.
+- Added SQLite semantic bucket indexing to narrow vector candidates for larger vaults.
+- Optimized title/link resolution with precomputed agent-scoped title maps.
+- Added CLI, JSON output, HTTP API and graph UI.
+- Added vault diagnostics: stats, broken links, orphans, validation and doctor.
+- Added agent namespaces under `agents/<agent-id>/`.
+- Added external MCP integration guidance through CLI subprocess wrappers.
+- Added large vault benchmark command and graph layout stress coverage.

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+## Local CLI
+
+```bash
+npm run dev -- --help
+```
+
+## Package Smoke Test
+
+```bash
+npm run pack:smoke
+```
+
+## Design Rules
+
+- Markdown files are the source of truth.
+- SQLite is a derived index and must remain rebuildable.
+- Domain parsing, graph analysis and layout should stay pure and testable.
+- CLI, HTTP, filesystem and SQLite code are adapters around application use cases.
+- MCP integration should live outside this package by wrapping the CLI with `--json`.

package/LICENSE

@@ -0,0 +1,23 @@
+SPDX-License-Identifier: MIT
+
+MIT License
+
+Copyright (c) 2026 Anderson Espindola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.