wicked-brain-mcp 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wicked_brain_mcp-0.1.1/.gitignore +1 -0
- wicked_brain_mcp-0.1.1/LICENSE +22 -0
- wicked_brain_mcp-0.1.1/PKG-INFO +85 -0
- wicked_brain_mcp-0.1.1/README.md +64 -0
- wicked_brain_mcp-0.1.1/pyproject.toml +36 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/__init__.py +13 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/__main__.py +3 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-capture.md +25 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-find.md +24 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-fork.md +32 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-health.md +25 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-init.md +24 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-merge.md +29 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-reconcile.md +33 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-reindex.md +25 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-save.md +29 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/commands/brain-sync.md +30 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/integrations/mcp-server/server.py +335 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/integrations/mcp-server/vault_ops.py +1899 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/auto_merge_exact_duplicates.py +159 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/export_okf.py +354 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/freshness_lint.py +412 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/link_graph.py +427 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/merge_notes.py +373 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/note_io.py +70 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/semantic_search.py +491 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/vault_git.py +344 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/vault_health.py +1081 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/vault_lock.py +133 -0
- wicked_brain_mcp-0.1.1/src/wicked_brain_mcp/scripts/vault_scan.py +104 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
*
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Eugeniu Ghelbur
|
|
4
|
+
Copyright (c) 2026 SimpliFixed Technologies, LLC
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: wicked-brain-mcp
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: MCP server for Wicked Brain: a plain-markdown memory vault your AI agents can search, read and write.
|
|
5
|
+
Project-URL: Homepage, https://brain.wickedlabs.gg
|
|
6
|
+
Project-URL: Repository, https://github.com/WickedAPI/wicked-brain
|
|
7
|
+
Project-URL: Issues, https://github.com/WickedAPI/wicked-brain/issues
|
|
8
|
+
Author: SimpliFixed Technologies, LLC
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ai-agents,claude,codex,markdown,mcp,memory,vault
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Topic :: Software Development
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Requires-Dist: mcp<2,>=1.0
|
|
19
|
+
Requires-Dist: pyyaml>=6
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# wicked-brain-mcp
|
|
23
|
+
|
|
24
|
+
The MCP server for [Wicked Brain](https://github.com/WickedAPI/wicked-brain): a plain-markdown
|
|
25
|
+
memory vault that your AI agents can search, read and write. The vault is a folder of markdown
|
|
26
|
+
files on your machine. No account, no telemetry, nothing uploaded.
|
|
27
|
+
|
|
28
|
+
This package gives any MCP client the 12 vault tools (search, read, save, capture, update,
|
|
29
|
+
patch, move, validate, backlinks, health, and the skill list). For the slash commands, hooks and
|
|
30
|
+
dashboard, install the full Wicked Brain plugin for Claude Code or Codex instead.
|
|
31
|
+
|
|
32
|
+
## Run it
|
|
33
|
+
|
|
34
|
+
You need [`uv`](https://docs.astral.sh/uv/). Point the server at your vault folder:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
WICKED_BRAIN_VAULT_PATH=/path/to/vault uvx wicked-brain-mcp
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### MCP client config
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"mcpServers": {
|
|
45
|
+
"wicked-brain": {
|
|
46
|
+
"command": "uvx",
|
|
47
|
+
"args": ["wicked-brain-mcp"],
|
|
48
|
+
"env": { "WICKED_BRAIN_VAULT_PATH": "/path/to/vault" }
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Codex (`~/.codex/config.toml`):
|
|
55
|
+
|
|
56
|
+
```toml
|
|
57
|
+
[mcp_servers.wicked-brain]
|
|
58
|
+
command = "uvx"
|
|
59
|
+
args = ["wicked-brain-mcp"]
|
|
60
|
+
env = { WICKED_BRAIN_VAULT_PATH = "/path/to/vault" }
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Your vault
|
|
64
|
+
|
|
65
|
+
The vault is just a folder of markdown files. Create it anywhere and point
|
|
66
|
+
`WICKED_BRAIN_VAULT_PATH` at it. For free version history, make it a git repository:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
mkdir ~/vault && cd ~/vault && git init
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Wicked Brain never deletes notes and never overwrites an existing one, but git lets you review
|
|
73
|
+
or undo any change an agent makes.
|
|
74
|
+
|
|
75
|
+
## Tools
|
|
76
|
+
|
|
77
|
+
Read-only: `brain_search`, `brain_read_note`, `brain_validate_note`, `brain_backlinks`,
|
|
78
|
+
`brain_vault_health`, `brain_list_skills`, `brain_get_skill`.
|
|
79
|
+
Additive (never overwrite): `brain_save_note`, `brain_capture`.
|
|
80
|
+
Edit existing notes (destructive hint): `brain_update_note`, `brain_replace_text`, `brain_move_note`.
|
|
81
|
+
|
|
82
|
+
All tools stay inside the vault folder. See the repository for the vault layout and the
|
|
83
|
+
optional end-to-end-encrypted sync.
|
|
84
|
+
|
|
85
|
+
MIT licensed.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# wicked-brain-mcp
|
|
2
|
+
|
|
3
|
+
The MCP server for [Wicked Brain](https://github.com/WickedAPI/wicked-brain): a plain-markdown
|
|
4
|
+
memory vault that your AI agents can search, read and write. The vault is a folder of markdown
|
|
5
|
+
files on your machine. No account, no telemetry, nothing uploaded.
|
|
6
|
+
|
|
7
|
+
This package gives any MCP client the 12 vault tools (search, read, save, capture, update,
|
|
8
|
+
patch, move, validate, backlinks, health, and the skill list). For the slash commands, hooks and
|
|
9
|
+
dashboard, install the full Wicked Brain plugin for Claude Code or Codex instead.
|
|
10
|
+
|
|
11
|
+
## Run it
|
|
12
|
+
|
|
13
|
+
You need [`uv`](https://docs.astral.sh/uv/). Point the server at your vault folder:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
WICKED_BRAIN_VAULT_PATH=/path/to/vault uvx wicked-brain-mcp
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
### MCP client config
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"mcpServers": {
|
|
24
|
+
"wicked-brain": {
|
|
25
|
+
"command": "uvx",
|
|
26
|
+
"args": ["wicked-brain-mcp"],
|
|
27
|
+
"env": { "WICKED_BRAIN_VAULT_PATH": "/path/to/vault" }
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Codex (`~/.codex/config.toml`):
|
|
34
|
+
|
|
35
|
+
```toml
|
|
36
|
+
[mcp_servers.wicked-brain]
|
|
37
|
+
command = "uvx"
|
|
38
|
+
args = ["wicked-brain-mcp"]
|
|
39
|
+
env = { WICKED_BRAIN_VAULT_PATH = "/path/to/vault" }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Your vault
|
|
43
|
+
|
|
44
|
+
The vault is just a folder of markdown files. Create it anywhere and point
|
|
45
|
+
`WICKED_BRAIN_VAULT_PATH` at it. For free version history, make it a git repository:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
mkdir ~/vault && cd ~/vault && git init
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Wicked Brain never deletes notes and never overwrites an existing one, but git lets you review
|
|
52
|
+
or undo any change an agent makes.
|
|
53
|
+
|
|
54
|
+
## Tools
|
|
55
|
+
|
|
56
|
+
Read-only: `brain_search`, `brain_read_note`, `brain_validate_note`, `brain_backlinks`,
|
|
57
|
+
`brain_vault_health`, `brain_list_skills`, `brain_get_skill`.
|
|
58
|
+
Additive (never overwrite): `brain_save_note`, `brain_capture`.
|
|
59
|
+
Edit existing notes (destructive hint): `brain_update_note`, `brain_replace_text`, `brain_move_note`.
|
|
60
|
+
|
|
61
|
+
All tools stay inside the vault folder. See the repository for the vault layout and the
|
|
62
|
+
optional end-to-end-encrypted sync.
|
|
63
|
+
|
|
64
|
+
MIT licensed.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wicked-brain-mcp"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
description = "MCP server for Wicked Brain: a plain-markdown memory vault your AI agents can search, read and write."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [{ name = "SimpliFixed Technologies, LLC" }]
|
|
14
|
+
keywords = ["mcp", "memory", "markdown", "vault", "ai-agents", "claude", "codex"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Topic :: Software Development",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"mcp>=1.0,<2",
|
|
24
|
+
"pyyaml>=6",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://brain.wickedlabs.gg"
|
|
29
|
+
Repository = "https://github.com/WickedAPI/wicked-brain"
|
|
30
|
+
Issues = "https://github.com/WickedAPI/wicked-brain/issues"
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
wicked-brain-mcp = "wicked_brain_mcp:main"
|
|
34
|
+
|
|
35
|
+
[tool.hatch.build.targets.wheel]
|
|
36
|
+
packages = ["src/wicked_brain_mcp"]
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""Wicked Brain MCP server: a plain-markdown memory vault for AI agents."""
|
|
2
|
+
import runpy
|
|
3
|
+
import sys
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
__all__ = ["main"]
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def main() -> None:
|
|
10
|
+
"""Console entry point: run the stdio MCP server."""
|
|
11
|
+
server = Path(__file__).resolve().parent / "integrations" / "mcp-server" / "server.py"
|
|
12
|
+
sys.argv[0] = str(server)
|
|
13
|
+
runpy.run_path(str(server), run_name="__main__")
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Quick capture - zero friction, saves a fact, pattern, or idea to concepts/ and links it from today's session note
|
|
3
|
+
category: vault
|
|
4
|
+
trigger-mode: proactive
|
|
5
|
+
triggers_en: ["remember that", "capture this", "note this down", "keep this in mind"]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
Use the wicked-brain skill. Execute `/brain-capture $ARGUMENTS`:
|
|
9
|
+
|
|
10
|
+
The optional argument is the text to capture. If not provided, pull the most recent worthwhile fact or idea from the conversation.
|
|
11
|
+
|
|
12
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first if it exists in the vault root.
|
|
13
|
+
2. Take the argument as the capture, or pull it from recent conversation context.
|
|
14
|
+
3. Search `concepts/` for a related existing note. If found, append to it (with today's date) rather than creating a near-duplicate.
|
|
15
|
+
4. If new: create `concepts/Title.md` with the minimal capture schema (`type: concept`, `date`, `tags: [concept]`, `ai-first: true`, `status: captured`, one-line body) - the documented capture exception in `references/ai-first-rules.md`: full enrichment happens later, not at capture time.
|
|
16
|
+
5. Add a brief link to it from today's session note (`sessions/YYYY-MM-DD.md`), creating that note if it doesn't exist yet.
|
|
17
|
+
|
|
18
|
+
Each write in steps 3-5 (the concept note, the session note) is a separate note - wrap each one individually with the shared vault lock per `references/write-rules.md`'s "Concurrent-safe writes" section, not the whole command.
|
|
19
|
+
6. **Version history (if enabled):** if `.git/` exists at the vault root, `git -C <vault> add -A && git -C <vault> commit -q -m "capture: <title>"`. Skip silently if there is no `.git/` directory. (Claude Code users get this automatically via `hooks/validate-ai-first.sh` - this step is the Codex CLI / no-hook-system path.)
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md`. The capture exception applies: minimal schema now, full enrichment later - but the preamble, `ai-first: true`, and a `date` are never optional even at capture time.
|
|
24
|
+
|
|
25
|
+
**Anti-fabrication:** Never invent context that wasn't actually said. If the source is ambiguous, capture it as stated and mark confidence `speculation` rather than upgrading it to `stated`.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Smart memory search - returns results with context, not just filenames
|
|
3
|
+
category: vault
|
|
4
|
+
triggers_en: ["find in memory", "search my memory", "where is", "what did I tell you about", "what do you remember about"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-find $ARGUMENTS`:
|
|
8
|
+
|
|
9
|
+
The argument is the search query.
|
|
10
|
+
|
|
11
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first if it exists in the vault root.
|
|
12
|
+
2. Search the vault for the query using the ranked search where it is available: the `brain_search` MCP tool, or `vault_ops.search` directly (`integrations/mcp-server/`). It fuses lexical (stopword-filtered, length-normalized) ranking with local semantic ranking when an embedding index exists, and applies freshness/supersession reranking so a superseded fact does not outrank the note that replaced it. Where no search tool is bound, grep the vault and read the top matches directly, applying the same judgement - ignore filler words, and do not let a long `sessions/` log outrank a canonical `entities/` or `projects/` note.
|
|
13
|
+
3. Try variations if results are sparse (synonyms, related terms).
|
|
14
|
+
4. Return results with context: note title, folder, a relevant excerpt, and what type of note it is.
|
|
15
|
+
5. If results are ambiguous, group them by type (entities, projects, decisions, concepts).
|
|
16
|
+
6. Offer to open, update, or link any of the found notes.
|
|
17
|
+
|
|
18
|
+
Do not just return filenames - return enough context for the user to act on the results.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, confidence levels where applicable. The vault is for future agent retrieval - not human reading.
|
|
23
|
+
|
|
24
|
+
**Anti-fabrication:** Search exhaustively before claiming any note, person, or file is absent - false absence is the most common failure mode - and never invent facts, entities, or dates (mark unknowns as `TBD`). See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Fork a project note - duplicate it under a new name, linked back to the original, so a derivative project starts with real context instead of a blank page
|
|
3
|
+
category: vault
|
|
4
|
+
triggers_en: ["fork this project", "clone this project in memory", "start a project based on"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-fork $ARGUMENTS`:
|
|
8
|
+
|
|
9
|
+
This forks the project's **memory** - its note in `projects/`. It does not touch code, does not run `git clone`, and does not create or move any repo directory. If the user also wants the actual code cloned, that is a separate, ordinary `git clone`/`cp -R` they do themselves (or ask you to run as a normal shell command) - this command only makes sure the new project's note starts with the parent's real context instead of a blank page, and that the two stay linked in the graph.
|
|
10
|
+
|
|
11
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first to find the vault path.
|
|
12
|
+
2. Resolve the **source** project: if `$ARGUMENTS` names one, search `projects/` for it - by exact name first, then a fuzzy/partial match. If nothing matches, list the closest candidates and ask rather than assuming; never fabricate a source note that doesn't exist (the false-absence rule cuts both ways here - don't claim a match that isn't real either).
|
|
13
|
+
3. Ask for (if not already given): the **new project's name**, and optionally its **repo path** if the user already knows where the forked code will live (fine to leave `TBD` - this command doesn't create that directory).
|
|
14
|
+
4. Search `projects/` for the new name first - if a note with that name already exists, stop and ask instead of overwriting it silently (same search-before-write rule as everything else).
|
|
15
|
+
5. Read the source note in full.
|
|
16
|
+
6. Compose the new note at `projects/<new name>.md`:
|
|
17
|
+
- Same frontmatter shape as the source (`references/ai-first-rules.md`'s `type: project` schema), with `date`/`updated` set to today, `status: planning` (a fork is a new direction, not automatically in lockstep with the parent's current status - the user can change this later), `repo:` set to what was given or `TBD`.
|
|
18
|
+
- `relations: { forked_from: ["[[projects/<source>]]"] }` (a documented typed edge - see `references/ai-first-rules.md` Rule 6).
|
|
19
|
+
- `## For future agent` preamble stating plainly it was forked from the source project on today's date, and that Overview below was seeded from the parent and needs review for what's actually different.
|
|
20
|
+
- An **Overview** section carried forward from the source (it's a legitimate, real starting point - not fabrication, since it's genuinely where this project started).
|
|
21
|
+
- Empty **Recent Activity** and **Key Decisions** sections - do NOT carry the parent's history forward into the fork's own sections; that history belongs to the parent, and copying it would misrepresent it as the fork's own.
|
|
22
|
+
7. Update the **source** note: add the inverse edge `relations: { forked_by: [...] }`, appending to (not replacing) any existing `relations:` block or `forked_by` list already there.
|
|
23
|
+
8. Append one line to today's session note: `**HH:MM** - fork | <source> -> <new name>`.
|
|
24
|
+
9. Report back: the new note's path, the source it was forked from, and a reminder that `repo:` is `TBD` if the user hasn't cloned the actual code yet.
|
|
25
|
+
|
|
26
|
+
**Concurrent-safe writes (non-negotiable):** wrap each of the two note writes (new note, source note update) separately with the shared vault lock - see `references/write-rules.md`. One note, one acquire/release pair.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
**AI-first rule:** The new note follows `references/ai-first-rules.md` in full - preamble, rich frontmatter, `ai-first: true`. It is not the redirect exception; a fork is a real, independent note from the moment it's created, not a pointer.
|
|
31
|
+
|
|
32
|
+
**Anti-fabrication:** Never invent a `repo:` path, a status, or history the user didn't state. Leave `repo: TBD` rather than guessing where forked code will live.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Run a memory health check - grouped by severity, detects duplicates, contradictions, stale claims, and structural issues
|
|
3
|
+
category: meta
|
|
4
|
+
triggers_en: ["memory health", "check the vault", "audit my memory", "memory diagnostics"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-health`:
|
|
8
|
+
|
|
9
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first to find the vault path.
|
|
10
|
+
2. Run the health scan from the skill root (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`): `uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json` (replace with the real vault path).
|
|
11
|
+
3. Also run the freshness lint - `uv run --directory "SKILL_ROOT" scripts/freshness_lint.py --path <vault> --json` - which enforces `references/freshness-policy.md`: every stored fact must be timeless, dated, or a pointer. FRESH-1 errors are present-tense claims about fast facts (counts, statuses, balances) with no `(as of ...)` stamp - the sentences that silently become lies.
|
|
12
|
+
4. Also run the typed-edge lint - `uv run --directory "SKILL_ROOT" scripts/link_graph.py --path <vault> --lint` - which validates any `relations:` typed edges (see `references/ai-first-rules.md` Rule 6 § Typed edges). Zero findings on a vault that uses no `relations:` blocks is normal, not an error.
|
|
13
|
+
5. Also check for near-identical duplicates the fork's auto-merge would act on: `uv run --directory "SKILL_ROOT" scripts/auto_merge_exact_duplicates.py --path <vault> --json` (dry run - this never writes on its own). These are notes similar enough (>=97%) that the background agent, if enabled, would merge them automatically; report them, but don't re-litigate the ones already merged.
|
|
14
|
+
6. Parse the JSON outputs and group findings by severity:
|
|
15
|
+
- **Critical**: unfilled template syntax, contradictions between notes, typed-edge contradiction cycles, code-fence-wrapped notes (frontmatter trapped in a leading fence - fix by unwrapping the fence, never by adding a second frontmatter block).
|
|
16
|
+
- **Warning**: near-duplicates below the auto-merge threshold (offer `/brain-merge` for these), missing required frontmatter fields, freshness violations (undated fast facts, aged `as of` stamps), typed-edge problems (unknown type, dangling target, self-edge).
|
|
17
|
+
- **Info**: orphaned notes, empty folders, missing inverse typed edges.
|
|
18
|
+
7. For safe, mechanical fixes (missing frontmatter fields, unwrapping a code-fence-wrapped note), offer to fix automatically. For anything requiring judgment (merging, resolving a contradiction, archiving), list it and ask for explicit confirmation before touching anything - never auto-apply.
|
|
19
|
+
8. Append one line to today's session note: `**HH:MM** - health | X critical, Y warnings, Z info`.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md`.
|
|
24
|
+
|
|
25
|
+
**Anti-fabrication:** Report findings exactly as the tools emit them - never round a warning up to critical or down to info, and never claim a clean scan when a tool call failed.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Bootstrap a new memory vault - fixed folder structure, operating manuals for both Claude Code and Codex CLI, index.md, CRITICAL_FACTS.md
|
|
3
|
+
category: meta
|
|
4
|
+
triggers_en: ["init memory", "bootstrap vault", "set up my memory", "create a new vault"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-init`:
|
|
8
|
+
|
|
9
|
+
1. Ask the user for the vault path if not already known (check for a `WICKED_BRAIN_VAULT_PATH` env var first).
|
|
10
|
+
2. Create the fixed folder structure if any part is missing: `projects/`, `entities/`, `decisions/`, `sessions/`, `concepts/`, `_trash/`. Do not invent additional top-level folders - this schema is intentionally fixed (see `references/vault-schema.md`).
|
|
11
|
+
3. Generate `_CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex CLI) from `references/claude-md-template.md`, filling in `{{VAULT_NAME}}` from the folder name (or ask the user). The two files carry the same content; neutralize Claude-specific tool names (`Read tool` -> `read files`, etc.) in `AGENTS.md` only.
|
|
12
|
+
4. Create `CRITICAL_FACTS.md` at the vault root if it doesn't exist: a short (~100-150 token) file for things worth loading every session (timezone, current focus). Leave it mostly empty with a comment explaining its purpose - do not fabricate content.
|
|
13
|
+
5. Generate `index.md`: a catalog of every existing note grouped by folder, one line each (`- [[Note Name]] - brief description` from frontmatter or the first line of body). If the vault is new and empty, write a stub explaining the format.
|
|
14
|
+
6. Create today's `sessions/YYYY-MM-DD.md` with an init entry: `**HH:MM** - init | Vault initialized with _CLAUDE.md, AGENTS.md, index.md, CRITICAL_FACTS.md`.
|
|
15
|
+
7. **Ask** whether to enable version history (Phase 2): a git repo local to the vault, giving free diff/rollback/blame with no server involved. This is the one place that turns it on - everything else (the write-time git hook on Claude Code, the commit-if-git-repo step in `/brain-save`/`/brain-capture`/`/brain-reconcile`, the MCP write path) only ever checks for `.git/` and stays silent if it's absent. If the user says yes and the vault is not already a git repo: `uv run --directory "SKILL_ROOT" scripts/vault_git.py --path <vault> --init --json`, which runs `git init`, writes a vault `.gitignore` (`.claude-runs/`, `*.semantic-index.json`, `.claude-lock`) if one doesn't already exist, and makes one initial commit covering everything just created. If the vault is already a git repo, say so and skip - never re-init.
|
|
16
|
+
8. Confirm what was written and tell the user to restart their Claude Code / Codex CLI session so the new files take effect. **Also check whether the platform-level install has actually been done** - this command only writes vault content; it does not symlink Claude Code's commands, copy Codex CLI's skill tree, or register the MCP server. If `/brain-*` or `$brain-*` don't already work in the user's current session, point them at `dist/claude-code/INSTALL.md` and/or `dist/codex-cli/INSTALL.md` (the latter has a global option, recommended for using the vault across more than one project folder) - a freshly-initialized vault does nothing on its own without that separate, one-time, per-machine step.
|
|
17
|
+
|
|
18
|
+
If `_CLAUDE.md` already exists: show a diff of what would change and ask before overwriting - never silently clobber a hand-edited operating manual. If `index.md` already exists, regenerate it (it's always meant to be a fresh catalog of current state).
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md`.
|
|
23
|
+
|
|
24
|
+
**Anti-fabrication:** Do not invent vault content, entity names, or project names that don't already exist in the vault when generating `index.md` - list only what's really there.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Merge two near-duplicate notes found by /brain-health into one - dry run by default, redirects the retired note rather than deleting it
|
|
3
|
+
category: meta
|
|
4
|
+
triggers_en: ["merge these notes", "merge duplicates", "combine these two notes"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-merge $ARGUMENTS`:
|
|
8
|
+
|
|
9
|
+
`/brain-health` finds duplicate pairs and stops - it is read-only by contract. This command does the merge: `scripts/merge_notes.py` (SKILL_ROOT's absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT` below) handles the mechanical half - frontmatter union, alias folding, and replacing the retired note with a `type: redirect` stub - and you compose the merged body, since deciding what actually contradicts between two notes is judgment, not mechanics.
|
|
10
|
+
|
|
11
|
+
**Nothing is ever deleted.** The surviving note keeps its path; the retired note's file stays in the vault, its content replaced by a short pointer (`references/write-rules.md`: never delete vault notes).
|
|
12
|
+
|
|
13
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first to find the vault path.
|
|
14
|
+
2. Resolve which two notes to merge. If `$ARGUMENTS` gives two paths, the first is **canonical** (survives) and the second is **retired** (becomes a redirect). If `$ARGUMENTS` is `--from-health`, run `uv run --directory "SKILL_ROOT" scripts/merge_notes.py --path <vault> --from-health` with no `--canonical` to list candidate pairs, then ask the user which to merge.
|
|
15
|
+
3. Read both notes in full.
|
|
16
|
+
4. Compose the merged body per `references/ai-first-rules.md`: one `## For future agent` preamble naming both source notes, keep both notes' provenance, list any genuine disagreement explicitly rather than silently picking a winner, carry forward every still-relevant `[[wikilink]]` from both. Write it to a scratch file - the same file is used for the dry run and the `--apply` run so the preview and the actual write are guaranteed identical.
|
|
17
|
+
5. Preview (dry run): `uv run --directory "SKILL_ROOT" scripts/merge_notes.py --path <vault> --canonical "<canonical rel path>" --retire "<retired rel path>" --merged-body-file <scratch file>`. Show the full output to the user - do not summarize it away.
|
|
18
|
+
6. Ask for explicit confirmation before applying.
|
|
19
|
+
7. Apply, once confirmed, by re-running the exact same command with `--apply` appended. If the vault is a git repo, `merge_notes.py` commits both files in one commit itself (Phase 2, version history) - no separate commit step needed here, on either platform.
|
|
20
|
+
8. Report back: which note survived, which became a redirect, frontmatter conflicts and which value won, any alias added, and any contradiction the merged body documented rather than resolved.
|
|
21
|
+
9. Append one line to today's session note: `**HH:MM** - merge | <retired> -> <canonical>`. This is a separate write from step 7 (which already locks internally via `merge_notes.py`) - wrap this one yourself per `references/write-rules.md`'s "Concurrent-safe writes" section.
|
|
22
|
+
|
|
23
|
+
If `merge_notes.py` refuses to run (malformed frontmatter, an ambiguous `--from-health` group, a path outside the vault), relay its error rather than retrying blindly or picking a canonical note for the user.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
**AI-first rule:** The retired note becomes `type: redirect` (the documented exception in `references/ai-first-rules.md`) - it carries no preamble, its only job is to point at the canonical note. Every other write follows the full rule.
|
|
28
|
+
|
|
29
|
+
**Anti-fabrication:** Do not resolve a genuine contradiction between the two notes by picking one side and dropping the other - list it instead.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Find and resolve contradictions in the vault - the memory maintains its own truth
|
|
3
|
+
category: thinking
|
|
4
|
+
triggers_en: ["find contradictions", "reconcile my memory", "fix conflicting facts"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-reconcile $ARGUMENTS`:
|
|
8
|
+
|
|
9
|
+
The optional argument is a topic or entity to focus on. If not provided, scan the whole vault.
|
|
10
|
+
|
|
11
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first if it exists. Read `index.md` for the full landscape.
|
|
12
|
+
2. Spawn parallel subagents to find contradictions:
|
|
13
|
+
- **Claims agent**: scan `concepts/` and `projects/` for factual claims; find pairs that contradict each other.
|
|
14
|
+
- **Entity agent**: scan `entities/` for outdated roles/status that conflict with a newer `timeline:` entry or a newer source.
|
|
15
|
+
- **Decisions agent**: scan `decisions/` and project Key Decisions sections for a decision that was reversed or superseded but never marked as such.
|
|
16
|
+
3. For each contradiction, evaluate: which claim is newer, which source is more authoritative, and whether this is a genuine contradiction or just someone's understanding evolving (evolution is not a contradiction).
|
|
17
|
+
4. Resolve each:
|
|
18
|
+
- **Clear winner**: rewrite the outdated note with current info and add a short `## History` note on what changed and why, with dates.
|
|
19
|
+
- **Genuinely ambiguous**: create a note in `decisions/` (`type: conflict`, `status: open`) documenting both sides and the evidence for each, for the user to decide.
|
|
20
|
+
- **Evolution**: update the entity/concept note's `timeline:` to reflect the current state (bi-temporal - append, don't overwrite) and keep the historical context.
|
|
21
|
+
5. Rebuild affected sections of `index.md`. Append one line to today's session note: `**HH:MM** - reconcile | X found, Y auto-resolved, Z flagged`.
|
|
22
|
+
|
|
23
|
+
Every write in steps 4-5 (each rewritten note, each new conflict note, index.md, the session note) is its own critical section - wrap each individually with the shared vault lock per `references/write-rules.md`'s "Concurrent-safe writes" section.
|
|
24
|
+
6. **Version history (if enabled):** if `.git/` exists at the vault root, `git -C <vault> add -A && git -C <vault> commit -q -m "reconcile: X found, Y auto-resolved"`. Skip silently if there is no `.git/` directory. (Claude Code users get this automatically via `hooks/validate-ai-first.sh` - this step is the Codex CLI / no-hook-system path.)
|
|
25
|
+
7. Report back: auto-resolved (old claim -> new claim and why), flagged for the user (genuinely ambiguous), and stale notes updated.
|
|
26
|
+
|
|
27
|
+
The vault should never contain two notes that disagree without knowing they disagree.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md`.
|
|
32
|
+
|
|
33
|
+
**Anti-fabrication:** Search exhaustively before claiming a contradiction is resolved - and never invent which source is "newer" or "more authoritative" when the note doesn't actually say.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Refresh the vault's semantic search index and report coverage before and after
|
|
3
|
+
category: meta
|
|
4
|
+
triggers_en: ["reindex memory", "rebuild semantic index", "refresh semantic search"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-reindex`:
|
|
8
|
+
|
|
9
|
+
Small gaps close automatically during normal `/brain-find` calls (the fork's auto-reindex upgrade - see `integrations/mcp-server/vault_ops.py`'s `_handle_stale_index`). Run this command for a full rebuild, to check coverage explicitly, or if Ollama was down when an automatic reindex would have fired.
|
|
10
|
+
|
|
11
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first to find the vault path. The skill root was given at session start as **Skill root**; substitute it for `SKILL_ROOT` below.
|
|
12
|
+
2. Measure coverage before changing the index:
|
|
13
|
+
```bash
|
|
14
|
+
uv run --directory "SKILL_ROOT" python -c 'import json, sys; from pathlib import Path; sys.path.insert(0, str(Path(sys.argv[1]) / "integrations" / "mcp-server")); from vault_ops import index_coverage; print(json.dumps(index_coverage(Path(sys.argv[2]).expanduser().resolve())))' "SKILL_ROOT" "VAULT_PATH"
|
|
15
|
+
```
|
|
16
|
+
Report `indexed`, `scanned`, `missing`, `pct_missing`. If `index` is false, say no readable semantic index exists yet rather than presenting `0/0` as coverage.
|
|
17
|
+
3. Run the incremental build: `uv run --directory "SKILL_ROOT" python scripts/semantic_search.py --path "VAULT_PATH" --build`. If it exits nonzero, stop and show the actionable error rather than claiming success. The common failure is Ollama not running or the embedding model not pulled (`ollama pull bge-m3`).
|
|
18
|
+
4. Re-run the coverage check from step 2.
|
|
19
|
+
5. Report coverage before/after, the builder's `new` count, and any degraded/dropped/capped paths from its stderr output (those notes are not fully searchable by meaning even after this run - capped means a very long note's middle section was skipped, though its ending is always embedded).
|
|
20
|
+
|
|
21
|
+
This command updates only the semantic index file; it never modifies markdown notes.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
**Anti-fabrication:** Report coverage and build counts exactly as the tools emit them. Never infer success from an unchanged file or a zero exit status when the builder itself reports dropped notes.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Save everything worth remembering from this conversation to the memory vault
|
|
3
|
+
category: vault
|
|
4
|
+
trigger-mode: proactive
|
|
5
|
+
triggers_en: ["save this", "save the conversation", "save to memory", "remember this"]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
Use the wicked-brain skill. Execute `/brain-save`:
|
|
9
|
+
|
|
10
|
+
1. Read `_CLAUDE.md` (or `AGENTS.md`) first if it exists in the vault root.
|
|
11
|
+
2. Scan the entire conversation and identify everything vault-worthy: decisions made, projects touched, people/tools/orgs mentioned (entities), reusable knowledge or patterns learned (concepts), and a session summary of what was actually done.
|
|
12
|
+
3. Group items by type and, for anything nontrivial, spawn parallel subagents so all types are handled simultaneously:
|
|
13
|
+
- **Entities agent**: search `entities/` for each person/org/tool mentioned; update the existing note's `timeline:` (bi-temporal - never overwrite `role`/`status`, append a new interval per `references/vault-schema.md`) or create a new entity note.
|
|
14
|
+
- **Projects agent**: search `projects/` for each project touched; update status, recent activity, and key decisions, or create a new project note.
|
|
15
|
+
- **Decisions agent**: for any decision made in this conversation, append it to the relevant project note's Key Decisions section, or create a standalone note in `decisions/` (ADR) for a decision that doesn't belong to one project.
|
|
16
|
+
- **Concepts agent**: search `concepts/` for related existing notes on anything learned or figured out; append or create.
|
|
17
|
+
4. Always write (or update) today's session note at `sessions/YYYY-MM-DD.md`: what was worked on, what was saved and where, and links to everything touched this session.
|
|
18
|
+
5. **Version history (if enabled):** if a `.git/` directory exists at the vault root, stage and commit everything you just wrote: `git -C <vault> add -A && git -C <vault> commit -q -m "save: <one-line summary>"`. This is the Codex CLI / no-hook-system path to Phase 2's version history - on Claude Code the same thing already happens automatically per write via `hooks/validate-ai-first.sh`, so this step is a no-op there in practice (nothing left to commit). If there is no `.git/` directory, skip this step silently - version history is opt-in per vault via `/brain-init`.
|
|
19
|
+
6. Report back: a clean list of what was saved and where.
|
|
20
|
+
|
|
21
|
+
Search before creating anything - duplicate notes are the exact rot this system exists to prevent. Never create an orphaned note; link everything from the session note.
|
|
22
|
+
|
|
23
|
+
**Concurrent-safe writes (non-negotiable):** wrap every individual note write (yours and each subagent's) with the shared vault lock - see `references/write-rules.md`'s "Concurrent-safe writes" section for the exact commands. One note, one acquire/release pair; never hold it across more than one write.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, confidence levels where applicable. If that path does not resolve from your working directory, search upward for it; if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The vault is for future agent retrieval - not human reading.
|
|
28
|
+
|
|
29
|
+
**Anti-fabrication:** Search exhaustively before claiming any note, person, or file is absent - false absence is the most common failure mode - and never invent facts, entities, or dates (mark unknowns as `TBD`). See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Sync the vault across your devices - push local changes, pull remote ones, and report any genuine conflicts
|
|
3
|
+
category: vault
|
|
4
|
+
triggers_en: ["sync my memory", "sync the vault", "push my notes", "pull my notes"]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use the wicked-brain skill. Execute `/brain-sync $ARGUMENTS`:
|
|
8
|
+
|
|
9
|
+
The optional argument is `push`, `pull`, or nothing (default: full bidirectional `sync`).
|
|
10
|
+
|
|
11
|
+
1. Check that sync is configured: `WICKED_BRAIN_SYNC_URL`, `WICKED_BRAIN_SYNC_TOKEN`, and `WICKED_BRAIN_SYNC_PASSPHRASE` must all be set in the environment. If any are missing, say so plainly and stop - do not guess a URL or invent a passphrase. Point the user at `sync_server/README.md` for how to stand up (or find) the sync server, and at this command's own frontmatter for the env var names.
|
|
12
|
+
2. Read `_CLAUDE.md` (or `AGENTS.md`) first to find the vault path. The skill root was given at session start as **Skill root**; substitute it for `SKILL_ROOT` below.
|
|
13
|
+
3. If this vault has never synced before (no `.sync-state.json` at the vault root) AND the vault currently has few or no notes, ask whether this is a brand-new device joining an existing synced vault - if so, use `--bootstrap` instead of `sync` so it fetches everything rather than diffing against nothing:
|
|
14
|
+
```bash
|
|
15
|
+
uv run --directory "SKILL_ROOT" python scripts/vault_sync.py bootstrap --path <vault> --url "$WICKED_BRAIN_SYNC_URL" --token "$WICKED_BRAIN_SYNC_TOKEN" --passphrase "$WICKED_BRAIN_SYNC_PASSPHRASE" --device "<a stable name for this machine>" --json
|
|
16
|
+
```
|
|
17
|
+
Bootstrap does NOT blindly overwrite this device's own vault: every device's own `/brain-init` creates local `_CLAUDE.md`/`index.md`/`CRITICAL_FACTS.md` before it ever syncs, so bootstrap checks each path first - a local file that already exists and differs from what's about to be pulled is saved as a conflict copy (`preserved` in the result), never silently discarded. Report those the same way you'd report a sync conflict (step 5 below).
|
|
18
|
+
4. Otherwise, run the requested mode (default `sync`):
|
|
19
|
+
```bash
|
|
20
|
+
uv run --directory "SKILL_ROOT" python scripts/vault_sync.py <push|pull|sync> --path <vault> --url "$WICKED_BRAIN_SYNC_URL" --token "$WICKED_BRAIN_SYNC_TOKEN" --passphrase "$WICKED_BRAIN_SYNC_PASSPHRASE" --device "<a stable name for this machine>" --json
|
|
21
|
+
```
|
|
22
|
+
Use a stable, human-readable `--device` value (e.g. the machine's hostname) - it's what conflict-copy filenames and pull commit messages will reference, so a consistent name makes history readable across devices.
|
|
23
|
+
5. Report back plainly from the JSON result: what was pushed, what was pulled, what got trashed locally (a note someone else deleted), and - most important - any conflicts (`sync`'s `conflicts` list, or bootstrap's `preserved` list). For each one, say which version won and where the losing version was saved (`conflict_copy`), and suggest the user review it and fold in anything worth keeping, the same way `/brain-merge` output is reviewed.
|
|
24
|
+
6. If the command fails outright (network error, wrong passphrase, auth rejected), relay the actual error - do not report success, and do not retry silently with different credentials.
|
|
25
|
+
|
|
26
|
+
Version history from git-backed local commits does **not** sync between devices - only current note content does. A pulled note lands in this device's own local git history (if this vault has one) via the same commit path `/brain-save` uses, but each device's history starts from wherever it joined.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
**Anti-fabrication:** Report exactly what `vault_sync.py` returned - never claim a clean sync when the command reported conflicts or errors, and never invent a device name, URL, or token value that wasn't actually configured.
|