@andespindola/brainlink 0.1.0-alpha.9 → 0.1.0-beta.1

package/docs/AGENT_USAGE.md

@@ -41,6 +41,10 @@ $HOME/.brainlink/vault
 
 Use `--vault <path>` for a one-off custom vault, or set `vault` in `brainlink.config.json` / `.brainlink.json` for a workspace-level custom default. Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhere else.
 
+You can also set `defaultAgent` in `brainlink.config.json` / `.brainlink.json` (for example `"defaultAgent": "coding-agent"`). When set, CLI commands and MCP calls reuse it when `--agent`/`agent` is not passed.
+
+`autoIndexOnWrite` (default: `true`) controls whether `add` and MCP write tools index right after writing.
+
 ## Agent Namespaces
 
 Each agent writes into a dedicated namespace under `agents/<agent-id>/`:
@@ -133,6 +137,7 @@ Rules:
 
 - Use a clear title.
 - Use `[[Note Title]]` for relationships.
+- Put priority markers near links when the relationship is important.
 - Use tags for retrieval.
 - Keep each note focused.
 - Prefer summaries over raw transcripts.
@@ -144,13 +149,22 @@ Brainlink only builds graph edges from Markdown `[[wiki links]]`.
 
 The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
 
+Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority:
+
+```md
+- [ ] Review [[Architecture]] priority: high
+Related: [[Incident Runbook]] #critical
+```
+
+Agents should use weighted graph output to sort relationships by importance. Edges expose `weight` and `priority`, where priority is one of `low`, `normal`, `high` or `critical`.
+
 Required write behavior:
 
 1. Choose a clear title for the new note.
 2. Look for an existing related concept with `search`, `links` or `backlinks`.
 3. Add at least one `[[Existing Note Title]]` link unless the note is intentionally a root concept.
 4. Add useful `#tags` for retrieval.
-5. Run `index` after the write.
+5. `add` writes are indexed by default. Only batch with explicit `--no-auto-index`, then run `index` once.
 6. Run `validate`, `broken-links` or `orphans` when the graph should be connected.
 
 Good linked note:
@@ -159,7 +173,6 @@ Good linked note:
 blink add "SQLite Index Rebuild" \
   --agent coding-agent \
   --content "Legacy derived indexes without agent columns are rebuilt because SQLite is disposable. Related: [[Architecture]], [[Agent Namespaces]]. #sqlite #architecture #decision"
-blink index
 blink validate --agent coding-agent
 ```
 
@@ -196,6 +209,54 @@ If the context is empty or weak:
 3. Inspect links and backlinks.
 4. Only then answer from general reasoning.
 
+## Optimized Agent Workflow (1 to 7)
+
+Use this exact loop for higher signal and lower noise:
+
+1. Read memory before decisions:
+   - `blink context "<task>" --agent "$BLINK_AGENT" --json`
+   - Add `--mode hybrid` for mixed retrieval.
+2. Keep vault structure deterministic:
+   - Keep shared knowledge in `agents/shared`.
+   - Keep private work-in-progress in your own agent namespace.
+3. Write durable notes only, with explicit links and tags:
+   - include at least one `[[...]]` link
+   - include `#tags` for retrieval
+4. Store only stable decisions and update an existing note when possible.
+5. Use cache-conscious read/refresh cycle:
+   - prefer targeted queries over broad dumps.
+   - avoid re-indexing unless note set changed.
+6. Run guardrails regularly:
+   - `npm run brainlink:sync -- --vault ./vault --agent "$BLINK_AGENT"`.
+   - the sync flow runs `index`, `stats`, `validate`, `broken-links`, `orphans` and a quick context probe.
+7. Before responding:
+   - cite sources from context output
+   - keep output anchored in retrieved references.
+
+Templates are available in `docs/templates` for quick note creation.
+
+Recommended template:
+
+```bash
+cp docs/templates/agent-note-template.md /tmp/agent-note.md
+```
+
+### MCP Usage for the Optimized Flow
+
+When using MCP, use this compact sequence for the same memory discipline:
+
+1. Bootstrap context:
+   - `brainlink_context` with `agent`, `query`, `mode: hybrid`, `limit`.
+2. Capture durable decisions:
+   - `brainlink_add_note` or `brainlink_add_file` with explicit `[[wiki links]]` and `#tags`.
+3. Run maintenance before handoff or before the next step:
+   - `brainlink_sync` with `agent`, `contextQuery`, `mode: hybrid`.
+4. Diagnose graph issues only when needed:
+   - `brainlink_validate`, `brainlink_broken_links`, `brainlink_orphans`.
+5. Inspect relationships:
+   - `brainlink_graph`.
+6. Use `brainlink_stats` for a quick health snapshot.
+
 ## Examples For Common Coding Agents
 
 These examples assume the agent can run shell commands in the user workspace.
@@ -286,8 +347,12 @@ $HOME/.brainlink/vault/
 
 ```bash
 blink add "Note Title" --vault ./vault --content "Markdown content"
+blink add "Note Title" --vault ./vault --content-file ./notes.md
+blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 ```
 
+`--content` and `--content-file` are mutually exclusive. Use `--no-auto-index` if you want to defer indexing in batch operations.
+
 This creates a slugged Markdown file with frontmatter and a heading.
 
 The CLI blocks common secret patterns by default. Do not use `--allow-sensitive` unless the vault is intentionally protected.
@@ -456,6 +521,7 @@ Available MCP tools:
 - `brainlink_context`
 - `brainlink_search`
 - `brainlink_add_note`
+- `brainlink_add_file`
 - `brainlink_index`
 - `brainlink_validate`
 - `brainlink_graph`
@@ -464,6 +530,8 @@ Available MCP tools:
 
 MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
+`brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
+
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```
@@ -552,4 +620,5 @@ Weak retrieval usually means:
 - Local embeddings are deterministic and provider-free; remote embedding providers are not implemented yet.
 - MCP integration is available through the `brainlink-mcp` stdio server.
 - HTTP API is local and unauthenticated.
-- Watch mode depends on platform filesystem watcher behavior.
+- Bucket vaults support S3-compatible `s3://bucket/prefix` URIs and use a local cache for SQLite indexes.
+- Watch mode depends on platform filesystem watcher behavior and is only supported for local filesystem vaults.

package/docs/ARCHITECTURE.md

@@ -105,13 +105,15 @@ Application code depends on domain rules and infrastructure interfaces.
 The infrastructure layer handles side effects:
 
 - reading Markdown files from disk
+- mirroring S3-compatible bucket Markdown into a local cache
 - writing Markdown notes
 - creating `.brainlink`
 - writing and querying SQLite
 - running FTS, semantic and hybrid retrieval
 - narrowing semantic candidates through SQLite embedding buckets before cosine scoring
 
-SQLite is an index, not the canonical storage model.
+SQLite is an index, not the canonical storage model. For bucket vaults, Markdown
+objects in the bucket remain canonical and SQLite is still local derived data.
 
 ## Indexing Flow
 
@@ -216,6 +218,23 @@ source note -> target note
 
 The `backlinks` command queries indexed links pointing to a target title. With `--agent`, it only returns links from that namespace.
 
+## Weighted Links
+
+Each indexed wiki link is stored as a graph edge with:
+
+- `weight`: numeric relationship strength.
+- `priority`: one of `low`, `normal`, `high` or `critical`.
+
+The parser derives weight from repeated links, task-list context, heading context and priority markers on the same line as a wiki link. Examples:
+
+```md
+Related: [[Architecture]]
+- [ ] Review [[Architecture]] priority: high
+Escalate [[Incident Runbook]] #critical
+```
+
+Backlink and graph readers return those fields to CLI JSON, HTTP API and MCP clients. Backlink queries use the normalized `to_title_key` column instead of applying `lower(...)` at read time.
+
 ## Context Building
 
 `context` uses search results and selects one chunk per document while staying inside an estimated token budget.
@@ -240,6 +259,7 @@ Relevant content
 Permanent:
 
 - Markdown files
+- S3-compatible Markdown objects when the vault is `s3://bucket/prefix`
 - optional Git history around the vault
 
 Canonical agent memory lives under:
@@ -251,6 +271,7 @@ vault/agents/<agent-id>/**/*.md
 Rebuildable:
 
 - `.brainlink/brainlink.db`
+- `$BRAINLINK_HOME/bucket-cache`
 - FTS records
 - local embedding vectors
 - local embedding bucket index

package/docs/RELEASE.md

@@ -32,7 +32,7 @@ blink context "release smoke" --vault ./tmp-vault --mode hybrid --json
 blink server --vault ./tmp-vault --host 127.0.0.1 --port 4321
 ```
 
-9. Verify the server refuses accidental public binds:
+9. Verify the server refuses public binds:
 
 ```bash
 blink server --vault ./tmp-vault --host 0.0.0.0

package/docs/templates/agent-namespace-bootstrap.md

@@ -0,0 +1,27 @@
+# Namespace Bootstrap for New Agent
+
+# <agent-id> Agent Notes
+
+## Purpose
+
+- Scope: 
+- Owner: 
+- Active project contexts:
+
+## Core Notes
+
+- [[Architecture]]
+- [[Coding Conventions]]
+- [[Runbook]]
+- [[Decision Log]]
+- [[Open Questions]]
+
+## Process
+
+1. Before task: context "<task>" --agent <agent-id> --json
+2. During task: document durable findings with explicit [[wiki links]]
+3. After task: add note + index + validation run
+
+## Tags
+
+#agent #<agent-id> #process

package/docs/templates/agent-note-template.md

@@ -0,0 +1,31 @@
+# Agent Note Template
+
+# <Title>
+
+## Context
+
+- What was decided or discovered.
+- Why this happened.
+- Expected impact or expected behavior.
+
+## References
+
+- [[Parent concept]]
+- [[Related decision]]
+
+## Notes
+
+#decision #<domain> #agent
+
+---
+
+## Changelog
+
+- YYYY-MM-DD: created
+
+## Durability checklist
+
+- The note has a clear title.
+- It links to at least one existing note (unless this is a root concept).
+- It has at least one `#tag`.
+- The content is stable knowledge, not one-off chat or session noise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0-beta.1",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -44,9 +44,11 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
+    "build": "npm run clean && npx --yes snyk test && tsc -p tsconfig.json",
     "dev": "tsx src/cli/main.ts",
     "dev:mcp": "tsx src/mcp/main.ts",
+    "brainlink:sync": "bash scripts/brainlink-sync.sh",
+    "security": "npx --yes snyk test",
     "test": "vitest run --config vitest.config.ts",
     "check": "npm run build && npm run test",
     "benchmark:large": "tsx src/benchmarks/large-vault.ts",
@@ -54,6 +56,7 @@
     "pack:smoke": "npm pack --dry-run"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1038.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
     "commander": "^14.0.2",