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.
- cerebro_mcp/__init__.py +3 -0
- cerebro_mcp/__main__.py +3 -0
- cerebro_mcp/cli.py +363 -0
- cerebro_mcp/config.py +248 -0
- cerebro_mcp/contradictions.py +499 -0
- cerebro_mcp/demo.py +102 -0
- cerebro_mcp/demo_vault/README.md +48 -0
- cerebro_mcp/demo_vault/agent-memory/streak-app/memory/MEMORY.md +4 -0
- cerebro_mcp/demo_vault/agent-memory/streak-app/memory/monetization.md +16 -0
- cerebro_mcp/demo_vault/agent-memory/streak-app/memory/project-overview.md +19 -0
- cerebro_mcp/demo_vault/agent-memory/streak-app/memory/release-process.md +12 -0
- cerebro_mcp/demo_vault/agent-memory/streak-app/memory/user-preferences.md +15 -0
- cerebro_mcp/demo_vault/agent-memory/streak-web/memory/MEMORY.md +3 -0
- cerebro_mcp/demo_vault/agent-memory/streak-web/memory/feedback-copy.md +14 -0
- cerebro_mcp/demo_vault/agent-memory/streak-web/memory/pricing.md +16 -0
- cerebro_mcp/demo_vault/agent-memory/streak-web/memory/site-stack.md +15 -0
- cerebro_mcp/demo_vault/cerebro.toml +35 -0
- cerebro_mcp/demo_vault/notes/Clippings/Why 7-day trials convert better.md +19 -0
- cerebro_mcp/demo_vault/notes/Daily/2026-11-03.md +14 -0
- cerebro_mcp/demo_vault/notes/Daily/2026-11-17.md +16 -0
- cerebro_mcp/demo_vault/notes/Decisions/2026-09-14 Precio y anuncios.md +29 -0
- cerebro_mcp/demo_vault/notes/Dev/Payments setup.md +24 -0
- cerebro_mcp/demo_vault/notes/Dev/Sync architecture.md +19 -0
- cerebro_mcp/demo_vault/notes/Ideas/Monetization brainstorm.md +20 -0
- cerebro_mcp/demo_vault/notes/Ideas/Streak widgets.md +13 -0
- cerebro_mcp/demo_vault/notes/Journal/2026-10-30.md +13 -0
- cerebro_mcp/demo_vault/notes/Marketing/Landing copy.md +22 -0
- cerebro_mcp/demo_vault/notes/Meetings/2026-10-08 Beta testers call.md +20 -0
- cerebro_mcp/demo_vault/notes/Projects/Launch plan.md +27 -0
- cerebro_mcp/demo_vault/notes/Projects/Roadmap 2026.md +17 -0
- cerebro_mcp/demo_vault/notes/Streak.md +32 -0
- cerebro_mcp/demo_vault/notes/Templates/Daily template.md +7 -0
- cerebro_mcp/demo_vault/notes/people/Marta Ruiz.md +12 -0
- cerebro_mcp/demo_vault/repo-docs/streak-app/AGENTS.md +9 -0
- cerebro_mcp/demo_vault/repo-docs/streak-app/docs/handoff-2026-11-18.md +26 -0
- cerebro_mcp/demo_vault/repo-docs/streak-app/docs/release-checklist.md +14 -0
- cerebro_mcp/demo_vault/repo-docs/streak-web/docs/pricing-page.md +20 -0
- cerebro_mcp/embeddings.py +166 -0
- cerebro_mcp/index.py +392 -0
- cerebro_mcp/notes.py +288 -0
- cerebro_mcp/query.py +386 -0
- cerebro_mcp/redact.py +161 -0
- cerebro_mcp/server.py +332 -0
- cerebro_mcp/sources.py +182 -0
- cerebro_mcp/text.py +54 -0
- cerebro_memory-0.2.0.dist-info/METADATA +264 -0
- cerebro_memory-0.2.0.dist-info/RECORD +50 -0
- cerebro_memory-0.2.0.dist-info/WHEEL +4 -0
- cerebro_memory-0.2.0.dist-info/entry_points.txt +4 -0
- cerebro_memory-0.2.0.dist-info/licenses/LICENSE +21 -0
cerebro_mcp/__init__.py
ADDED
cerebro_mcp/__main__.py
ADDED
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)
|