cerebro-memory 0.2.0__py3-none-any.whl

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.
Files changed (50) hide show
  1. cerebro_mcp/__init__.py +3 -0
  2. cerebro_mcp/__main__.py +3 -0
  3. cerebro_mcp/cli.py +363 -0
  4. cerebro_mcp/config.py +248 -0
  5. cerebro_mcp/contradictions.py +499 -0
  6. cerebro_mcp/demo.py +102 -0
  7. cerebro_mcp/demo_vault/README.md +48 -0
  8. cerebro_mcp/demo_vault/agent-memory/streak-app/memory/MEMORY.md +4 -0
  9. cerebro_mcp/demo_vault/agent-memory/streak-app/memory/monetization.md +16 -0
  10. cerebro_mcp/demo_vault/agent-memory/streak-app/memory/project-overview.md +19 -0
  11. cerebro_mcp/demo_vault/agent-memory/streak-app/memory/release-process.md +12 -0
  12. cerebro_mcp/demo_vault/agent-memory/streak-app/memory/user-preferences.md +15 -0
  13. cerebro_mcp/demo_vault/agent-memory/streak-web/memory/MEMORY.md +3 -0
  14. cerebro_mcp/demo_vault/agent-memory/streak-web/memory/feedback-copy.md +14 -0
  15. cerebro_mcp/demo_vault/agent-memory/streak-web/memory/pricing.md +16 -0
  16. cerebro_mcp/demo_vault/agent-memory/streak-web/memory/site-stack.md +15 -0
  17. cerebro_mcp/demo_vault/cerebro.toml +35 -0
  18. cerebro_mcp/demo_vault/notes/Clippings/Why 7-day trials convert better.md +19 -0
  19. cerebro_mcp/demo_vault/notes/Daily/2026-11-03.md +14 -0
  20. cerebro_mcp/demo_vault/notes/Daily/2026-11-17.md +16 -0
  21. cerebro_mcp/demo_vault/notes/Decisions/2026-09-14 Precio y anuncios.md +29 -0
  22. cerebro_mcp/demo_vault/notes/Dev/Payments setup.md +24 -0
  23. cerebro_mcp/demo_vault/notes/Dev/Sync architecture.md +19 -0
  24. cerebro_mcp/demo_vault/notes/Ideas/Monetization brainstorm.md +20 -0
  25. cerebro_mcp/demo_vault/notes/Ideas/Streak widgets.md +13 -0
  26. cerebro_mcp/demo_vault/notes/Journal/2026-10-30.md +13 -0
  27. cerebro_mcp/demo_vault/notes/Marketing/Landing copy.md +22 -0
  28. cerebro_mcp/demo_vault/notes/Meetings/2026-10-08 Beta testers call.md +20 -0
  29. cerebro_mcp/demo_vault/notes/Projects/Launch plan.md +27 -0
  30. cerebro_mcp/demo_vault/notes/Projects/Roadmap 2026.md +17 -0
  31. cerebro_mcp/demo_vault/notes/Streak.md +32 -0
  32. cerebro_mcp/demo_vault/notes/Templates/Daily template.md +7 -0
  33. cerebro_mcp/demo_vault/notes/people/Marta Ruiz.md +12 -0
  34. cerebro_mcp/demo_vault/repo-docs/streak-app/AGENTS.md +9 -0
  35. cerebro_mcp/demo_vault/repo-docs/streak-app/docs/handoff-2026-11-18.md +26 -0
  36. cerebro_mcp/demo_vault/repo-docs/streak-app/docs/release-checklist.md +14 -0
  37. cerebro_mcp/demo_vault/repo-docs/streak-web/docs/pricing-page.md +20 -0
  38. cerebro_mcp/embeddings.py +166 -0
  39. cerebro_mcp/index.py +392 -0
  40. cerebro_mcp/notes.py +288 -0
  41. cerebro_mcp/query.py +386 -0
  42. cerebro_mcp/redact.py +161 -0
  43. cerebro_mcp/server.py +332 -0
  44. cerebro_mcp/sources.py +182 -0
  45. cerebro_mcp/text.py +54 -0
  46. cerebro_memory-0.2.0.dist-info/METADATA +264 -0
  47. cerebro_memory-0.2.0.dist-info/RECORD +50 -0
  48. cerebro_memory-0.2.0.dist-info/WHEEL +4 -0
  49. cerebro_memory-0.2.0.dist-info/entry_points.txt +4 -0
  50. cerebro_memory-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,3 @@
1
+ """cerebro-memory: a local, read-only index over Markdown notes and AI agent memories."""
2
+
3
+ __version__ = "0.2.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
cerebro_mcp/cli.py ADDED
@@ -0,0 +1,363 @@
1
+ """Command line: init, index, search, contradictions, serve, doctor, demo."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import datetime as dt
7
+ import json
8
+ import sys
9
+ import textwrap
10
+ from pathlib import Path
11
+
12
+ from . import __version__
13
+ from . import config as config_mod
14
+ from .config import Config, ConfigError
15
+
16
+
17
+ def _utf8() -> None:
18
+ for stream in (sys.stdout, sys.stderr):
19
+ try:
20
+ stream.reconfigure(encoding="utf-8")
21
+ except (AttributeError, ValueError):
22
+ pass
23
+
24
+
25
+ def _err(msg: str) -> None:
26
+ print(f"cerebro: {msg}", file=sys.stderr)
27
+
28
+
29
+ def _embedder(cfg: Config, text: bool):
30
+ if text:
31
+ return None
32
+ from .embeddings import E5Embedder
33
+
34
+ return E5Embedder(cfg.model)
35
+
36
+
37
+ def _load(args) -> Config:
38
+ return config_mod.load(getattr(args, "config", None))
39
+
40
+
41
+ # ---------- init ----------
42
+
43
+
44
+ def cmd_init(args) -> int:
45
+ target = Path(args.config).expanduser() if getattr(args, "config", None) else None
46
+ if target is None:
47
+ import os
48
+
49
+ env = os.environ.get("CEREBRO_CONFIG")
50
+ target = Path(env).expanduser() if env else config_mod.user_config_file()
51
+ if target.exists() and not args.force:
52
+ _err(f"{target} already exists; not overwriting it (use --force to replace it)")
53
+ return 1
54
+ vault = Path(args.vault).expanduser().resolve() if args.vault else None
55
+ if vault is not None and not vault.is_dir():
56
+ _err(f"warning: vault folder does not exist yet: {vault}")
57
+ memory = None
58
+ if not args.no_agent_memory:
59
+ candidate = Path.home() / ".claude" / "projects"
60
+ if candidate.is_dir():
61
+ memory = candidate
62
+ target.parent.mkdir(parents=True, exist_ok=True)
63
+ target.write_text(config_mod.starter(vault, memory), encoding="utf-8", newline="\n")
64
+ print(f"wrote {target}")
65
+ if vault:
66
+ print(f" source notes -> {vault}")
67
+ if memory:
68
+ print(f" source claude-memory -> {memory}")
69
+ if not vault and not memory:
70
+ print(" no sources yet: edit the file and add a [[source]]")
71
+ print("next: cerebro index")
72
+ return 0
73
+
74
+
75
+ # ---------- index ----------
76
+
77
+
78
+ def cmd_index(args) -> int:
79
+ from . import index
80
+
81
+ cfg = _load(args)
82
+ summary = index.run(cfg, _embedder(cfg, args.text), full=args.full)
83
+ for w in summary.warnings:
84
+ _err(f"warning: {w}")
85
+ print(summary)
86
+ for name, n in summary.by_source.items():
87
+ print(f" {name:<20} {n:>6} files")
88
+ print(f"index: {cfg.db}")
89
+ return 0
90
+
91
+
92
+ # ---------- search ----------
93
+
94
+
95
+ def _one_line(text: str, width: int = 160) -> str:
96
+ flat = " ".join(text.split())
97
+ return flat if len(flat) <= width else flat[: width - 1] + "…"
98
+
99
+
100
+ def cmd_search(args) -> int:
101
+ from . import index, query
102
+
103
+ cfg = _load(args)
104
+ if not cfg.db.exists():
105
+ _err("no index yet: run `cerebro index` first")
106
+ return 1
107
+ conn = index.connect(cfg.db)
108
+ try:
109
+ r = query.search(
110
+ conn,
111
+ _embedder(cfg, args.text),
112
+ args.query,
113
+ hidden_scopes=cfg.privacy.hidden_scopes,
114
+ source=args.source,
115
+ scope=args.scope,
116
+ type=args.type,
117
+ since=args.since,
118
+ until=args.until,
119
+ limit=args.limit,
120
+ )
121
+ except query.QueryError as e:
122
+ _err(str(e))
123
+ return 2
124
+ finally:
125
+ conn.close()
126
+ if args.json:
127
+ print(json.dumps(r, ensure_ascii=False, indent=2))
128
+ return 0
129
+ print(f"mode: {r['mode']}")
130
+ if not r["results"]:
131
+ print("no results")
132
+ for i, x in enumerate(r["results"], 1):
133
+ where = " · ".join(v for v in (x["source"], x["project"], x["date"]) if v)
134
+ flag = " [untrusted]" if x["untrusted"] else ""
135
+ print(f"{i:>2}. {x['title']} [{where}]{flag}")
136
+ print(f" {x['path']} ({'+'.join(x['signals'])} {x['score']})")
137
+ print(f" {_one_line(x['snippet'])}")
138
+ return 0
139
+
140
+
141
+ # ---------- contradictions ----------
142
+
143
+
144
+ def format_pairs(pairs: list[dict]) -> str:
145
+ out = []
146
+ for i, p in enumerate(pairs, 1):
147
+ headline = "; ".join(
148
+ f"{v['kind']}: {' / '.join(v['older'])} -> {' / '.join(v['newer'])}" for v in p["values"]
149
+ )
150
+ out.append(f"{i}. {headline}")
151
+ for label in ("older", "newer"):
152
+ s = p[label]
153
+ flag = " [untrusted]" if s["untrusted"] else ""
154
+ out.append(f" {label:<5} {s['date'] or '----------'} {s['path']}{flag}")
155
+ out.append(textwrap.indent(_one_line(s["snippet"], 150), " "))
156
+ out.append("")
157
+ return "\n".join(out).rstrip()
158
+
159
+
160
+ def cmd_contradictions(args) -> int:
161
+ from . import contradictions, index, query
162
+
163
+ cfg = _load(args)
164
+ if not cfg.db.exists():
165
+ _err("no index yet: run `cerebro index` first")
166
+ return 1
167
+ conn = index.connect(cfg.db)
168
+ try:
169
+ r = contradictions.find(
170
+ conn,
171
+ _embedder(cfg, args.text),
172
+ args.topic,
173
+ hidden_scopes=cfg.privacy.hidden_scopes,
174
+ scope=args.scope,
175
+ across_sources=args.across_sources,
176
+ limit=args.limit,
177
+ )
178
+ except query.QueryError as e:
179
+ _err(str(e))
180
+ return 2
181
+ finally:
182
+ conn.close()
183
+ if args.json:
184
+ print(json.dumps(r, ensure_ascii=False, indent=2))
185
+ return 0
186
+ print(f"mode: {r['mode']}")
187
+ print(format_pairs(r["pairs"]) if r["pairs"] else "no contradictions found on that topic")
188
+ return 0
189
+
190
+
191
+ # ---------- serve ----------
192
+
193
+
194
+ def cmd_serve(args) -> int:
195
+ from .server import serve
196
+
197
+ serve(_load(args), text_only=args.text)
198
+ return 0
199
+
200
+
201
+ # ---------- doctor ----------
202
+
203
+
204
+ def _age(iso: str | None) -> str:
205
+ if not iso:
206
+ return "never"
207
+ try:
208
+ delta = dt.datetime.now() - dt.datetime.fromisoformat(iso)
209
+ except ValueError:
210
+ return iso
211
+ minutes = int(delta.total_seconds() // 60)
212
+ if minutes < 60:
213
+ return f"{minutes} min ago"
214
+ if minutes < 48 * 60:
215
+ return f"{minutes // 60} h ago"
216
+ return f"{minutes // (60 * 24)} days ago"
217
+
218
+
219
+ def cmd_doctor(args) -> int:
220
+ import platform
221
+
222
+ from . import embeddings, index, sources
223
+
224
+ ok = True
225
+ print(f"cerebro-memory {__version__} · Python {platform.python_version()} · {platform.system()}")
226
+ found = config_mod.find(getattr(args, "config", None))
227
+ if found is None or not found.is_file():
228
+ print(f"[!!] config: not found{f' ({found})' if found else ''}. Run `cerebro init`.")
229
+ return 1
230
+ try:
231
+ cfg = config_mod.load(found)
232
+ except ConfigError as e:
233
+ print(f"[!!] config: {e}")
234
+ return 1
235
+ print(f"[ok] config: {cfg.path}")
236
+ if not cfg.sources:
237
+ print("[!!] no sources configured")
238
+ ok = False
239
+ for s in cfg.sources:
240
+ if not s.path.is_dir():
241
+ print(f"[!!] source {s.name} ({s.kind}): folder not found: {s.path}")
242
+ ok = False
243
+ continue
244
+ n = sources.count(s)
245
+ mark = "ok" if n else "--"
246
+ print(f"[{mark}] source {s.name} ({s.kind}, scope {s.scope}): {n} files in {s.path}")
247
+ if cfg.privacy.hidden_scopes:
248
+ print(f"[ok] hidden scopes: {', '.join(cfg.privacy.hidden_scopes)}")
249
+ print(f"[ok] redaction packs: {', '.join(cfg.privacy.redact) or 'none'}")
250
+ if cfg.db.exists():
251
+ conn = index.connect(cfg.db)
252
+ try:
253
+ n_notes = conn.execute("select count(*) from notes").fetchone()[0]
254
+ n_private = conn.execute("select count(*) from notes where private = 1").fetchone()[0]
255
+ vectors = index.has_vectors(conn)
256
+ when = index.get_meta(conn, "indexed_at")
257
+ model = index.get_meta(conn, "model")
258
+ vec = conn.vec
259
+ finally:
260
+ conn.close()
261
+ size = cfg.db.stat().st_size / 1024
262
+ print(
263
+ f"[ok] index: {cfg.db} ({size:.0f} KB) · {n_notes} notes ({n_private} private) · "
264
+ f"updated {_age(when)} · {'vectors: ' + model if vectors and model else 'text only'}"
265
+ )
266
+ print(f"[{'ok' if vec else '--'}] sqlite-vec: {'loaded' if vec else 'not loadable here (numpy fallback)'}")
267
+ else:
268
+ print(f"[--] index: not built yet ({cfg.db}). Run `cerebro index`.")
269
+ spec = embeddings.spec(cfg.model)
270
+ if embeddings.is_cached(cfg.model):
271
+ print(f"[ok] model: {spec.repo} ({spec.file}) cached in {embeddings.cache_dir()}")
272
+ else:
273
+ print(
274
+ f"[--] model: {spec.repo} not cached yet (~{spec.size_mb} MB, downloaded on the first "
275
+ f"`cerebro index`; until then use --text). Cache: {embeddings.cache_dir()}"
276
+ )
277
+ return 0 if ok else 1
278
+
279
+
280
+ # ---------- demo ----------
281
+
282
+
283
+ def cmd_demo(args) -> int:
284
+ from .demo import run_demo
285
+
286
+ return run_demo(keep=args.keep, text=args.text)
287
+
288
+
289
+ # ---------- parser ----------
290
+
291
+
292
+ def build_parser() -> argparse.ArgumentParser:
293
+ common = argparse.ArgumentParser(add_help=False)
294
+ common.add_argument("--config", default=argparse.SUPPRESS, help="path to cerebro.toml")
295
+
296
+ ap = argparse.ArgumentParser(
297
+ prog="cerebro",
298
+ description="A local, read-only index over your Markdown notes and your AI agents' memories, served over MCP.",
299
+ )
300
+ ap.add_argument("--version", action="version", version=f"cerebro-memory {__version__}")
301
+ ap.add_argument("--config", default=None, help="path to cerebro.toml")
302
+ sub = ap.add_subparsers(dest="cmd", required=True)
303
+
304
+ p = sub.add_parser("init", parents=[common], help="write a starter cerebro.toml")
305
+ p.add_argument("--vault", help="your notes folder (Markdown / Obsidian)")
306
+ p.add_argument("--no-agent-memory", action="store_true", help="do not add ~/.claude/projects")
307
+ p.add_argument("--force", action="store_true", help="overwrite an existing file")
308
+ p.set_defaults(fn=cmd_init)
309
+
310
+ p = sub.add_parser("index", parents=[common], help="update the index (incremental by content hash)")
311
+ p.add_argument("--full", action="store_true", help="delete the index and rebuild it")
312
+ p.add_argument("--text", action="store_true", help="text only (FTS5), no embedding model")
313
+ p.set_defaults(fn=cmd_index)
314
+
315
+ p = sub.add_parser("search", parents=[common], help="hybrid search")
316
+ p.add_argument("query")
317
+ p.add_argument("--source")
318
+ p.add_argument("--scope")
319
+ p.add_argument("--type")
320
+ p.add_argument("--since", help="YYYY, YYYY-MM or YYYY-MM-DD")
321
+ p.add_argument("--until", help="YYYY, YYYY-MM or YYYY-MM-DD")
322
+ p.add_argument("--text", action="store_true", help="text only (FTS5), no embedding model")
323
+ p.add_argument("--limit", type=int, default=8)
324
+ p.add_argument("--json", action="store_true")
325
+ p.set_defaults(fn=cmd_search)
326
+
327
+ p = sub.add_parser("contradictions", parents=[common], help="pairs of fragments that state different values")
328
+ p.add_argument("topic")
329
+ p.add_argument("--across-sources", action="store_true", help="only pairs from different sources")
330
+ p.add_argument("--scope")
331
+ p.add_argument("--limit", type=int, default=5)
332
+ p.add_argument("--text", action="store_true", help="text only, no embedding model")
333
+ p.add_argument("--json", action="store_true")
334
+ p.set_defaults(fn=cmd_contradictions)
335
+
336
+ p = sub.add_parser("serve", parents=[common], help="MCP server over stdio (clients launch it)")
337
+ p.add_argument("--text", action="store_true", help="text only, no embedding model")
338
+ p.set_defaults(fn=cmd_serve)
339
+
340
+ p = sub.add_parser("doctor", parents=[common], help="check config, sources, index and model")
341
+ p.set_defaults(fn=cmd_doctor)
342
+
343
+ p = sub.add_parser("demo", help="index the bundled demo vault and show what disagrees")
344
+ p.add_argument("--keep", action="store_true", help="keep the temp copy and print how to explore it")
345
+ p.add_argument("--text", action="store_true", help="text only, no embedding model")
346
+ p.set_defaults(fn=cmd_demo)
347
+ return ap
348
+
349
+
350
+ def main(argv: list[str] | None = None) -> int:
351
+ _utf8()
352
+ args = build_parser().parse_args(argv)
353
+ try:
354
+ return args.fn(args)
355
+ except ConfigError as e:
356
+ _err(str(e))
357
+ return 1
358
+ except KeyboardInterrupt:
359
+ return 130
360
+
361
+
362
+ if __name__ == "__main__":
363
+ raise SystemExit(main())
cerebro_mcp/config.py ADDED
@@ -0,0 +1,248 @@
1
+ """`cerebro.toml`: where it is looked up, what it may contain, and how it is validated.
2
+
3
+ Lookup order: `--config PATH`, `$CEREBRO_CONFIG`, `./cerebro.toml`, then the
4
+ user config dir (`platformdirs`). `~` and environment variables expand in every
5
+ path; relative paths resolve against the directory of the loaded file.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ import tomllib
12
+ from dataclasses import dataclass, field
13
+ from pathlib import Path
14
+
15
+ import platformdirs
16
+
17
+ APP = "cerebro"
18
+ FILENAME = "cerebro.toml"
19
+ KINDS = ("vault", "claude-code-memory", "glob")
20
+ DEFAULT_SCOPE = "default"
21
+ DEFAULT_PRIVATE_FOLDERS = ("private",)
22
+ DEFAULT_REDACT = ("secrets", "cards")
23
+ REDACT_PACKS = ("secrets", "cards", "mx")
24
+ DEFAULT_GLOB_INCLUDE = ("**/*.md",)
25
+
26
+
27
+ class ConfigError(ValueError):
28
+ """The config file is missing or invalid. The message is meant for a human."""
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class Source:
33
+ name: str
34
+ kind: str
35
+ path: Path
36
+ scope: str = DEFAULT_SCOPE
37
+ exclude: tuple[str, ...] = ()
38
+ include: tuple[str, ...] = ()
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class Privacy:
43
+ private_folders: tuple[str, ...] = DEFAULT_PRIVATE_FOLDERS
44
+ private_frontmatter: str = "private"
45
+ redact: tuple[str, ...] = DEFAULT_REDACT
46
+ hidden_scopes: tuple[str, ...] = ()
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class Config:
51
+ db: Path
52
+ proposals: Path
53
+ sources: tuple[Source, ...] = ()
54
+ privacy: Privacy = field(default_factory=Privacy)
55
+ model: str | None = None # embedding model key; None = the default one
56
+ path: Path | None = None # the file it was loaded from
57
+
58
+ def source(self, name: str) -> Source | None:
59
+ return next((s for s in self.sources if s.name == name), None)
60
+
61
+
62
+ def user_config_file() -> Path:
63
+ return Path(platformdirs.user_config_dir(APP, appauthor=False)) / FILENAME
64
+
65
+
66
+ def default_db() -> Path:
67
+ return Path(platformdirs.user_cache_dir(APP, appauthor=False)) / "index.db"
68
+
69
+
70
+ def default_proposals() -> Path:
71
+ return Path(platformdirs.user_cache_dir(APP, appauthor=False)) / "proposals"
72
+
73
+
74
+ def find(explicit: str | os.PathLike | None = None) -> Path | None:
75
+ """The config file to use, or None when there is none anywhere."""
76
+ if explicit:
77
+ return Path(explicit).expanduser()
78
+ env = os.environ.get("CEREBRO_CONFIG")
79
+ if env:
80
+ return Path(env).expanduser()
81
+ here = Path.cwd() / FILENAME
82
+ if here.is_file():
83
+ return here
84
+ user = user_config_file()
85
+ if user.is_file():
86
+ return user
87
+ return None
88
+
89
+
90
+ def expand(value: str, base: Path) -> Path:
91
+ """`~` and `$VARS` expand; a relative path is relative to `base`."""
92
+ p = Path(os.path.expandvars(os.path.expanduser(value)))
93
+ if not p.is_absolute():
94
+ p = base / p
95
+ return Path(os.path.normpath(p))
96
+
97
+
98
+ def _strings(value, what: str) -> tuple[str, ...]:
99
+ if value is None:
100
+ return ()
101
+ if isinstance(value, str):
102
+ return (value,)
103
+ if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
104
+ raise ConfigError(f"{what} must be a list of strings")
105
+ return tuple(value)
106
+
107
+
108
+ def parse(data: dict, base: Path, path: Path | None = None) -> Config:
109
+ """Validate a parsed TOML document. `base` resolves relative paths."""
110
+ index = data.get("index", {}) or {}
111
+ if not isinstance(index, dict):
112
+ raise ConfigError("[index] must be a table")
113
+ db = expand(index["db"], base) if index.get("db") else default_db()
114
+ proposals = expand(index["proposals"], base) if index.get("proposals") else default_proposals()
115
+ model = index.get("model")
116
+ if model is not None and not isinstance(model, str):
117
+ raise ConfigError("[index] model must be a string")
118
+
119
+ raw_sources = data.get("source", [])
120
+ if not isinstance(raw_sources, list):
121
+ raise ConfigError("use [[source]] (an array of tables) for sources")
122
+ sources: list[Source] = []
123
+ seen: set[str] = set()
124
+ for i, s in enumerate(raw_sources, 1):
125
+ if not isinstance(s, dict):
126
+ raise ConfigError(f"source #{i} must be a table")
127
+ name = s.get("name")
128
+ if not isinstance(name, str) or not name.strip():
129
+ raise ConfigError(f"source #{i} needs a name")
130
+ name = name.strip()
131
+ if ":" in name or "/" in name or "\\" in name:
132
+ raise ConfigError(f"source {name!r}: the name cannot contain ':', '/' or '\\'")
133
+ if name in seen:
134
+ raise ConfigError(f"source name {name!r} is used twice")
135
+ seen.add(name)
136
+ kind = s.get("kind", "vault")
137
+ if kind not in KINDS:
138
+ raise ConfigError(f"source {name!r}: kind must be one of {', '.join(KINDS)}")
139
+ if not isinstance(s.get("path"), str) or not s["path"].strip():
140
+ raise ConfigError(f"source {name!r} needs a path")
141
+ scope = s.get("scope", DEFAULT_SCOPE)
142
+ if not isinstance(scope, str) or not scope.strip():
143
+ raise ConfigError(f"source {name!r}: scope must be a non-empty string")
144
+ include = _strings(s.get("include"), f"source {name!r}: include")
145
+ if kind == "glob" and not include:
146
+ include = DEFAULT_GLOB_INCLUDE
147
+ unknown = set(s) - {"name", "kind", "path", "scope", "exclude", "include"}
148
+ if unknown:
149
+ raise ConfigError(f"source {name!r}: unknown keys {', '.join(sorted(unknown))}")
150
+ sources.append(
151
+ Source(
152
+ name=name,
153
+ kind=kind,
154
+ path=expand(s["path"], base),
155
+ scope=scope.strip(),
156
+ exclude=_strings(s.get("exclude"), f"source {name!r}: exclude"),
157
+ include=include,
158
+ )
159
+ )
160
+
161
+ p = data.get("privacy", {}) or {}
162
+ if not isinstance(p, dict):
163
+ raise ConfigError("[privacy] must be a table")
164
+ redact = _strings(p.get("redact", list(DEFAULT_REDACT)), "privacy.redact")
165
+ bad = [r for r in redact if r not in REDACT_PACKS]
166
+ if bad:
167
+ raise ConfigError(f"privacy.redact: unknown pack(s) {', '.join(bad)} (known: {', '.join(REDACT_PACKS)})")
168
+ private_fm = p.get("private_frontmatter", "private")
169
+ if not isinstance(private_fm, str):
170
+ raise ConfigError("privacy.private_frontmatter must be a string")
171
+ privacy = Privacy(
172
+ private_folders=_strings(p.get("private_folders", list(DEFAULT_PRIVATE_FOLDERS)), "privacy.private_folders"),
173
+ private_frontmatter=private_fm.strip(),
174
+ redact=redact,
175
+ hidden_scopes=_strings(p.get("hidden_scopes"), "privacy.hidden_scopes"),
176
+ )
177
+ return Config(db=db, proposals=proposals, sources=tuple(sources), privacy=privacy, model=model, path=path)
178
+
179
+
180
+ def load(path: str | os.PathLike | None = None) -> Config:
181
+ """Find and load the config. Raises ConfigError with a readable message."""
182
+ found = find(path)
183
+ if found is None:
184
+ raise ConfigError(
185
+ f"no {FILENAME} found (looked at --config, $CEREBRO_CONFIG, ./{FILENAME} and "
186
+ f"{user_config_file()}). Run `cerebro init` to create one."
187
+ )
188
+ if not found.is_file():
189
+ raise ConfigError(f"config file not found: {found}")
190
+ try:
191
+ data = tomllib.loads(found.read_text(encoding="utf-8"))
192
+ except tomllib.TOMLDecodeError as e:
193
+ raise ConfigError(f"{found}: invalid TOML: {e}") from e
194
+ resolved = found.resolve()
195
+ return parse(data, resolved.parent, resolved)
196
+
197
+
198
+ def _toml_str(value: str) -> str:
199
+ return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
200
+
201
+
202
+ def starter(vault: Path | None, agent_memory: Path | None) -> str:
203
+ """The text of a starter `cerebro.toml`."""
204
+ lines = [
205
+ "# cerebro.toml: what cerebro indexes and what it keeps private.",
206
+ "# Paths accept ~ and $VARS; relative paths are relative to this file.",
207
+ "",
208
+ "[index]",
209
+ f"# db = {_toml_str(str(default_db()))}",
210
+ f"# proposals = {_toml_str(str(default_proposals()))}",
211
+ "",
212
+ ]
213
+ if vault is not None:
214
+ lines += [
215
+ "[[source]]",
216
+ 'name = "notes"',
217
+ 'kind = "vault"',
218
+ f"path = {_toml_str(str(vault))}",
219
+ 'scope = "personal"',
220
+ 'exclude = ["Templates/**"]',
221
+ "",
222
+ ]
223
+ if agent_memory is not None:
224
+ lines += [
225
+ "[[source]]",
226
+ 'name = "claude-memory"',
227
+ 'kind = "claude-code-memory"',
228
+ f"path = {_toml_str(str(agent_memory))}",
229
+ 'scope = "work"',
230
+ "",
231
+ ]
232
+ lines += [
233
+ "# Any Markdown matched by globs (project = first path segment):",
234
+ "# [[source]]",
235
+ '# name = "handoffs"',
236
+ '# kind = "glob"',
237
+ '# path = "~/code"',
238
+ '# include = ["*/docs/**/*.md", "*/AGENTS.md", "*/CLAUDE.md"]',
239
+ '# scope = "work"',
240
+ "",
241
+ "[privacy]",
242
+ 'private_folders = ["private", "people"] # any path segment, case-insensitive',
243
+ 'private_frontmatter = "private" # `private: true` in frontmatter',
244
+ 'redact = ["secrets", "cards"] # add "mx" for CLABE/RFC/CURP/INE',
245
+ "hidden_scopes = [] # indexed, returned only when asked for",
246
+ "",
247
+ ]
248
+ return "\n".join(lines)