pantheon-opencode 1.6.0-beta.9 → 1.6.1

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 (140) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +144 -365
  4. package/README.md +124 -607
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +504 -141
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +22 -13
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +850 -45
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +99 -383
  29. package/scripts/install/interrupt.mjs +78 -0
  30. package/scripts/install/migrate.mjs +49 -25
  31. package/scripts/install/model-picker.mjs +218 -250
  32. package/scripts/install/opencode-state.mjs +91 -0
  33. package/scripts/install/opencode-version.mjs +83 -21
  34. package/scripts/install/opencode.mjs +1675 -187
  35. package/scripts/install/plan-artifact.mjs +517 -0
  36. package/scripts/install/plan.mjs +475 -0
  37. package/scripts/install/plugin.mjs +214 -27
  38. package/scripts/install/prompt-result.mjs +2 -0
  39. package/scripts/install/run-record.mjs +115 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +93 -8
  43. package/scripts/install/v2-capabilities.mjs +205 -0
  44. package/scripts/install/venv.mjs +90 -47
  45. package/scripts/install/verify.mjs +128 -0
  46. package/scripts/install/vision-prompt.mjs +173 -0
  47. package/scripts/install-mcp.mjs +2 -2
  48. package/scripts/manifest-inventory.mjs +49 -3
  49. package/scripts/mcp_persistence.py +1535 -1050
  50. package/scripts/memory_mcp.py +12 -843
  51. package/scripts/node-engine-policy.mjs +85 -0
  52. package/scripts/package-evidence.mjs +10 -2
  53. package/scripts/postinstall.mjs +26 -26
  54. package/scripts/probe-pantheon-cost.mjs +118 -19
  55. package/scripts/prune.mjs +9 -3
  56. package/scripts/reconcile.mjs +325 -0
  57. package/scripts/release-gates.mjs +687 -0
  58. package/scripts/restore.mjs +222 -0
  59. package/scripts/run-node-tests.mjs +24 -8
  60. package/scripts/sync-artifacts.mjs +19 -7
  61. package/scripts/sync-tui.mjs +5 -1
  62. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  63. package/scripts/uninstall.mjs +369 -34
  64. package/scripts/update.mjs +164 -0
  65. package/scripts/validate-node-engine-policy.mjs +13 -0
  66. package/scripts/version-check.mjs +34 -1
  67. package/scripts/versioning.mjs +23 -3
  68. package/scripts/vision-status.mjs +682 -0
  69. package/skills-lock.json +8 -8
  70. package/src/agents/aphrodite.md +13 -10
  71. package/src/agents/apollo.md +4 -5
  72. package/src/agents/athena.md +74 -46
  73. package/src/agents/demeter.md +10 -7
  74. package/src/agents/gaia.md +0 -1
  75. package/src/agents/hephaestus.md +4 -3
  76. package/src/agents/hermes.md +10 -9
  77. package/src/agents/iris.md +6 -1
  78. package/src/agents/mnemosyne.md +10 -4
  79. package/src/agents/nyx.md +4 -4
  80. package/src/agents/prometheus.md +12 -11
  81. package/src/agents/talos.md +6 -0
  82. package/src/agents/zeus.md +84 -56
  83. package/src/instructions/agent-return-format.instructions.md +12 -41
  84. package/src/instructions/memory-protocol.instructions.md +5 -11
  85. package/src/instructions/test-economy.instructions.md +12 -0
  86. package/src/instructions/yagni.instructions.md +6 -15
  87. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  88. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  89. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  90. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  91. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  92. package/src/mcp/_pantheon_paths.py +24 -0
  93. package/src/mcp/mcp_codemap_module.py +86 -18
  94. package/src/mcp/mcp_persistence.py +1535 -1050
  95. package/src/mcp/memory_mcp.py +444 -94
  96. package/src/mcp/pantheon_vision.py +285 -41
  97. package/src/mcp/requirements-mcp.txt +6 -1
  98. package/src/mcp/requirements-vision.txt +1 -1
  99. package/src/pantheon/context-pruner.ts +541 -0
  100. package/src/pantheon/cost-command.ts +901 -60
  101. package/src/pantheon/delegation-enforce.ts +160 -23
  102. package/src/pantheon/goal-loop.ts +11 -8
  103. package/src/pantheon/guard-path.ts +162 -0
  104. package/src/pantheon/memory-context.ts +1017 -0
  105. package/src/pantheon/model-agents.ts +19 -0
  106. package/src/pantheon/model-command.ts +218 -56
  107. package/src/pantheon/model-pricing.ts +536 -0
  108. package/src/pantheon/presets.mjs +2 -0
  109. package/src/pantheon/task-result-guard.ts +50 -14
  110. package/src/pantheon/v2-bounded-read.ts +654 -0
  111. package/src/pantheon/v2-bridge.ts +27 -0
  112. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  113. package/src/pantheon/v2-execute-after.ts +135 -24
  114. package/src/pantheon/v2-model-overrides.ts +275 -0
  115. package/src/pantheon/v2-shell-hooks.ts +260 -0
  116. package/src/pantheon/v2-tools.ts +89 -35
  117. package/src/pantheon/v2-unsupported.mjs +34 -7
  118. package/src/pantheon/v2-vision.ts +622 -0
  119. package/src/pantheon/vision-local.ts +531 -0
  120. package/src/pantheon/vision.ts +1166 -116
  121. package/src/plugin-v2.ts +1039 -171
  122. package/src/plugin.ts +37 -13
  123. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  124. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  125. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  126. package/src/plugins/tui/dist/tui.js +1 -1
  127. package/src/plugins/tui/package-lock.json +15 -15
  128. package/src/plugins/tui/package.json +7 -5
  129. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  130. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  131. package/src/routing.yml +50 -5
  132. package/src/skills/agent-coordination/SKILL.md +7 -2
  133. package/src/skills/artifact-management/SKILL.md +5 -1
  134. package/src/skills/auto-continue/SKILL.md +14 -6
  135. package/src/skills/codemap/SKILL.md +1 -1
  136. package/src/skills/memory-bank/SKILL.md +21 -13
  137. package/src/skills/session-goal/SKILL.md +12 -22
  138. package/src/skills/spec-driven-development/SKILL.md +3 -1
  139. package/src/skills/worktrees/SKILL.md +30 -11
  140. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -10,6 +10,12 @@ half was compensating for a query bug rather than adding recall. See
10
10
  Recall is therefore purely lexical. A query that shares no token with a
11
11
  stored document will not retrieve it; there is no embedding to fall back on.
12
12
 
13
+ Storage is bounded and optional-expiry: an entry larger than
14
+ ``PANTHEON_MEMORY_MAX_ENTRY_BYTES`` (default 64 KiB, the same bound the
15
+ Persistence MCP applies to checkpoints) is rejected rather than truncated, and
16
+ an entry stored with ``ttl_seconds`` is hidden from search once it expires until
17
+ ``memory_forget(expired_only=True)`` removes it explicitly.
18
+
13
19
  Tools:
14
20
  memory_store — Store a value (auto-indexed into FTS5 by trigger)
15
21
  memory_search — FTS5 BM25 keyword search with optional freshness decay
@@ -17,6 +23,9 @@ Tools:
17
23
  memory_forget — Delete by ID or key
18
24
  memory_list — Chronological listing
19
25
  memory_stats — DB statistics
26
+ code_index — Index code entities
27
+ code_query — Search indexed code entities
28
+ code_neighbors — Find related code entities
20
29
 
21
30
  Usage:
22
31
  python scripts/memory_mcp.py
@@ -27,15 +36,18 @@ from __future__ import annotations
27
36
  import contextlib
28
37
  import functools
29
38
  import json
39
+ import logging
40
+ import os
30
41
  import sqlite3
31
42
  import time
32
43
  from datetime import UTC, datetime
33
44
  from pathlib import Path
34
- from typing import Annotated, Any
45
+ from typing import Annotated, Any, Literal
35
46
 
36
- from _pantheon_paths import pantheon_home
47
+ from _pantheon_paths import pantheon_home, trusted_project_root
37
48
  from fastmcp import FastMCP
38
49
  from pydantic import BeforeValidator, Field
50
+ from typing_extensions import TypedDict
39
51
 
40
52
  try:
41
53
  import mcp_codemap_module as _codemap
@@ -68,6 +80,17 @@ def _reset_test_state() -> None:
68
80
  _get_db.cache_clear()
69
81
 
70
82
 
83
+ # ── Store Limits ─────────────────────────────────────────────────────────────
84
+ # A memory entry is bounded on write: unlike a truncated value, a rejected one
85
+ # is recoverable (store a summary, raise the cap, or keep the long text in a
86
+ # file), so over-cap input is refused, never shortened. The default matches
87
+ # MAX_CONTEXT_CONTENT_BYTES in mcp_persistence.py / docs/MEMORY.md so
88
+ # the two stores agree on what "one entry" is allowed to cost.
89
+
90
+ DEFAULT_MAX_ENTRY_BYTES = 64 * 1024
91
+ MAX_ENTRY_BYTES_ENV = "PANTHEON_MEMORY_MAX_ENTRY_BYTES"
92
+ MAX_TTL_SECONDS = 31_536_000 # 365 days, same ceiling as Persistence TTL
93
+
71
94
  SCHEMA_SQL = """
72
95
  CREATE TABLE IF NOT EXISTS memories (
73
96
  id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -76,7 +99,8 @@ CREATE TABLE IF NOT EXISTS memories (
76
99
  value TEXT NOT NULL,
77
100
  metadata TEXT NOT NULL DEFAULT '{}',
78
101
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
79
- updated_at TEXT NOT NULL DEFAULT (datetime('now'))
102
+ updated_at TEXT NOT NULL DEFAULT (datetime('now')),
103
+ expires_at TEXT
80
104
  );
81
105
 
82
106
  CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_ns_key
@@ -119,11 +143,64 @@ mcp = FastMCP(
119
143
  "index, so a query must share a token with the stored text to match."
120
144
  ),
121
145
  )
146
+ _LOGGER = logging.getLogger(__name__)
147
+
148
+ # TypedDict comes from typing_extensions, not typing: pydantic only builds a
149
+ # schema for typing.TypedDict on Python >= 3.12, and FastMCP builds the output
150
+ # schema during @mcp.tool registration (see _SUPPORTS_TYPEDDICT in pydantic).
151
+ # Using typing.TypedDict here aborted the import on the supported 3.11 range.
152
+
153
+
154
+ class MemorySearchErrorDetail(TypedDict):
155
+ """Safe, typed error detail returned when a memory search cannot run."""
156
+
157
+ type: Literal["DatabaseUnavailableError", "MemorySearchError"]
158
+ message: str
159
+
160
+
161
+ class MemorySearchError(TypedDict):
162
+ """Structured error envelope for ``memory_search``."""
163
+
164
+ error: MemorySearchErrorDetail
122
165
 
123
166
 
124
167
  # ── Database ──────────────────────────────────────────────────────────────────
125
168
 
126
169
 
170
+ def _ensure_entry_lifecycle_schema(conn: sqlite3.Connection) -> bool:
171
+ """Add the ``expires_at`` column to a pre-existing ``memories`` table.
172
+
173
+ Databases created before per-entry TTL have no ``expires_at`` column, and
174
+ ``CREATE TABLE IF NOT EXISTS`` does not add one. The ALTER is guarded by a
175
+ ``PRAGMA table_info`` read, so a second open — of the same connection or of
176
+ a database already migrated — is a no-op instead of an error, and no row is
177
+ rewritten or dropped. NULL means "never expires", which is exactly the
178
+ lifetime every existing row already had.
179
+
180
+ Args:
181
+ conn: Open connection with the current schema applied.
182
+
183
+ Returns:
184
+ True when the column was added by this call, False when it was already
185
+ present.
186
+ """
187
+ columns = {row[1] for row in conn.execute("PRAGMA table_info(memories)")}
188
+ added = False
189
+ if "expires_at" not in columns:
190
+ try:
191
+ conn.execute("ALTER TABLE memories ADD COLUMN expires_at TEXT")
192
+ conn.commit()
193
+ added = True
194
+ except sqlite3.OperationalError:
195
+ # A concurrent server won the race; the column now exists.
196
+ _LOGGER.debug("expires_at column added by a concurrent open")
197
+ conn.execute(
198
+ "CREATE INDEX IF NOT EXISTS idx_memories_expires_at ON memories(expires_at)"
199
+ )
200
+ conn.commit()
201
+ return added
202
+
203
+
127
204
  @functools.cache
128
205
  def _get_db() -> sqlite3.Connection:
129
206
  """Get or create the SQLite connection singleton.
@@ -139,6 +216,7 @@ def _get_db() -> sqlite3.Connection:
139
216
  conn.execute("PRAGMA busy_timeout=5000")
140
217
  conn.execute("PRAGMA foreign_keys=ON")
141
218
  conn.executescript(SCHEMA_SQL)
219
+ _ensure_entry_lifecycle_schema(conn)
142
220
  if _codemap is not None:
143
221
  with contextlib.suppress(Exception):
144
222
  _codemap.ensure_codemap_schema(conn)
@@ -304,22 +382,21 @@ def _build_fts_query(query: str) -> str:
304
382
 
305
383
  Tokens surviving both filters are still prefix-matched, so a query term
306
384
  retrieves documents containing a longer word that starts with it. If every
307
- token is a stopword the unfiltered tokens are matched exactly, so an
308
- all-stopword query degrades to a literal lookup rather than to no results.
385
+ token is a stopword, the query is empty and returns no results.
309
386
 
310
387
  Args:
311
388
  query: Raw, user-supplied search text.
312
389
 
313
390
  Returns:
314
- An FTS5 expression (terms joined with ``OR``), or ``""`` for an empty
315
- query.
391
+ An FTS5 expression (terms joined with ``OR``), or ``""`` when there are
392
+ no searchable terms.
316
393
  """
317
394
  words = [word for word in query.split() if word]
318
395
  if not words:
319
396
  return ""
320
397
  content = [word for word in words if word.lower() not in _STOPWORDS]
321
398
  if not content:
322
- content = words
399
+ return ""
323
400
  return " OR ".join(
324
401
  f'"{word}"*' if len(word) >= _MIN_PREFIX_LEN else f'"{word}"'
325
402
  for word in content
@@ -350,6 +427,80 @@ def _parse_metadata(row: dict[str, Any]) -> dict[str, Any]:
350
427
  return row
351
428
 
352
429
 
430
+ # ── Entry Size Accounting ─────────────────────────────────────────────────────
431
+ # One size definition shared by the write guard and ``memory_stats``: the UTF-8
432
+ # bytes of every stored text column. SQLite mirrors it in ``_ENTRY_BYTES_SQL``
433
+ # with ``length(cast(x AS blob))``, which counts bytes rather than characters.
434
+
435
+ _ENTRY_BYTES_SQL = (
436
+ "length(cast(coalesce(value, '') as blob))"
437
+ " + length(cast(coalesce(metadata, '') as blob))"
438
+ " + length(cast(coalesce(namespace, '') as blob))"
439
+ " + length(cast(coalesce(key, '') as blob))"
440
+ )
441
+
442
+
443
+ def _entry_size_bytes(
444
+ value: str,
445
+ namespace: str = "default",
446
+ key: str | None = None,
447
+ metadata: str = "{}",
448
+ ) -> int:
449
+ """Return the serialized size of an entry in UTF-8 bytes."""
450
+ return sum(
451
+ len(part.encode("utf-8"))
452
+ for part in (value, metadata or "{}", namespace or "", key or "")
453
+ )
454
+
455
+
456
+ def _max_entry_bytes() -> int:
457
+ """Return the per-entry cap, honouring ``PANTHEON_MEMORY_MAX_ENTRY_BYTES``.
458
+
459
+ Read per call, not at import, so a changed environment takes effect without
460
+ a server restart. An unparseable or non-positive override falls back to the
461
+ default and logs once per call instead of failing the write path.
462
+ """
463
+ raw = os.environ.get(MAX_ENTRY_BYTES_ENV, "").strip()
464
+ if not raw:
465
+ return DEFAULT_MAX_ENTRY_BYTES
466
+ try:
467
+ cap = int(raw)
468
+ except ValueError:
469
+ _LOGGER.warning(
470
+ "%s=%r is not an integer; using the default %d bytes",
471
+ MAX_ENTRY_BYTES_ENV,
472
+ raw,
473
+ DEFAULT_MAX_ENTRY_BYTES,
474
+ )
475
+ return DEFAULT_MAX_ENTRY_BYTES
476
+ if cap <= 0:
477
+ _LOGGER.warning(
478
+ "%s=%r must be positive; using the default %d bytes",
479
+ MAX_ENTRY_BYTES_ENV,
480
+ raw,
481
+ DEFAULT_MAX_ENTRY_BYTES,
482
+ )
483
+ return DEFAULT_MAX_ENTRY_BYTES
484
+ return cap
485
+
486
+
487
+ def _entry_size_violation(actual: int, cap: int) -> str:
488
+ """Describe an over-cap write so the caller can act without guessing."""
489
+ cap_label = (
490
+ f"{cap:,} bytes"
491
+ if cap < _BYTE_UNIT
492
+ else f"{cap:,} bytes ({cap // _BYTE_UNIT} KiB)"
493
+ )
494
+ return (
495
+ f"serialized entry is {actual:,} UTF-8 bytes "
496
+ f"(value + metadata + namespace + key); maximum is {cap_label}. "
497
+ f"Store a summary here and keep the full text elsewhere, or raise the "
498
+ f"cap by setting {MAX_ENTRY_BYTES_ENV}={actual:,} in the memory "
499
+ "server's environment (any positive integer). Over-cap entries are "
500
+ "rejected, never truncated."
501
+ )
502
+
503
+
353
504
  # ── Ranking ───────────────────────────────────────────────────────────────────
354
505
 
355
506
 
@@ -376,20 +527,17 @@ def _fetch_created_at_map(db: sqlite3.Connection, ids: list[int]) -> dict[int, s
376
527
  ids: Memory row IDs to look up.
377
528
 
378
529
  Returns:
379
- Mapping of id -> created_at ISO string. Empty on failure.
530
+ Mapping of id -> created_at ISO string.
380
531
  """
381
532
  created_at_map: dict[int, str] = {}
382
533
  if not ids:
383
534
  return created_at_map
384
- try:
385
- placeholders = ",".join("?" * len(ids))
386
- rows = db.execute(
387
- f"SELECT id, created_at FROM memories WHERE id IN ({placeholders})",
388
- ids,
389
- ).fetchall()
390
- created_at_map = {r["id"]: r["created_at"] for r in rows}
391
- except Exception:
392
- created_at_map = {}
535
+ placeholders = ",".join("?" * len(ids))
536
+ rows = db.execute(
537
+ f"SELECT id, created_at FROM memories WHERE id IN ({placeholders})",
538
+ ids,
539
+ ).fetchall()
540
+ created_at_map = {r["id"]: r["created_at"] for r in rows}
393
541
  return created_at_map
394
542
 
395
543
 
@@ -437,6 +585,53 @@ def _score_hits(
437
585
  return ranked[:top_k]
438
586
 
439
587
 
588
+ def _search_candidates(
589
+ db: sqlite3.Connection,
590
+ fts_query: str,
591
+ namespace: str | None,
592
+ limit: int,
593
+ include_expired: bool,
594
+ ) -> list[tuple[int, float]]:
595
+ """Fetch the over-fetched FTS5 candidate list, expiry-filtered in SQL.
596
+
597
+ Args:
598
+ db: Active SQLite connection.
599
+ fts_query: FTS5 ``MATCH`` expression from ``_build_fts_query``.
600
+ namespace: Optional namespace filter.
601
+ limit: Candidate limit (callers over-fetch 2x ``top_k``).
602
+ include_expired: Keep entries whose ``expires_at`` has passed.
603
+
604
+ Returns:
605
+ ``(id, bm25)`` pairs, best first.
606
+ """
607
+ params: list[Any] = [fts_query]
608
+ filters = ""
609
+ if not include_expired:
610
+ # Lexicographic comparison of stored ISO-8601 UTC strings is
611
+ # chronological, so no date parsing is needed in SQL. Rows written
612
+ # before TTL support have expires_at NULL and stay visible.
613
+ filters += " AND (memories.expires_at IS NULL OR memories.expires_at > ?)"
614
+ params.append(_now_iso())
615
+ if namespace:
616
+ filters += " AND memories.namespace = ?"
617
+ params.append(namespace)
618
+ params.append(limit)
619
+ # ``rank`` is BM25 negated by FTS5 (lower = better), so -rank is the
620
+ # relevance score. It is selected explicitly so the value is available for
621
+ # scoring rather than only for ordering. The join to ``memories`` applies
622
+ # the expiry filter before LIMIT, so an expired entry cannot consume one of
623
+ # the candidate slots.
624
+ rows = db.execute(
625
+ f"""SELECT memories_fts.rowid AS rowid, -rank AS bm25
626
+ FROM memories_fts
627
+ JOIN memories ON memories.id = memories_fts.rowid
628
+ WHERE memories_fts MATCH ?{filters}
629
+ ORDER BY rank LIMIT ?""",
630
+ params,
631
+ ).fetchall()
632
+ return [(r["rowid"], r["bm25"]) for r in rows]
633
+
634
+
440
635
  # ── Tools ─────────────────────────────────────────────────────────────────────
441
636
 
442
637
  # ── Argument Validation ─────────────────────────────────────────────────────────
@@ -484,11 +679,18 @@ def _metadata_must_be_json_string(value: Any) -> Any:
484
679
  )
485
680
 
486
681
 
487
- def _collect_store_violations(value: str, metadata: str) -> tuple[list[str], list[str]]:
682
+ def _collect_store_violations(
683
+ value: str,
684
+ metadata: str,
685
+ namespace: str = "default",
686
+ key: str | None = None,
687
+ ttl_seconds: Any = None,
688
+ ) -> tuple[list[str], list[str]]:
488
689
  """Collect every in-body ``memory_store`` violation, plus any examples.
489
690
 
490
691
  Returns ``(violations, examples)`` so the caller reports all of them in one
491
692
  message instead of returning on the first problem it happens to notice.
693
+ The size check measures the stripped value, which is what gets stored.
492
694
  """
493
695
  violations: list[str] = []
494
696
  examples: list[str] = []
@@ -503,6 +705,25 @@ def _collect_store_violations(value: str, metadata: str) -> tuple[list[str], lis
503
705
  f"(got invalid JSON: {exc})"
504
706
  )
505
707
  examples.append(METADATA_EXAMPLE)
708
+ if ttl_seconds is not None:
709
+ if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int):
710
+ violations.append(
711
+ "ttl_seconds must be a positive integer number of seconds "
712
+ f"(got {_json_type_name(ttl_seconds)}); omit it for an entry "
713
+ "that never expires"
714
+ )
715
+ examples.append("ttl_seconds=86400")
716
+ elif not 1 <= ttl_seconds <= MAX_TTL_SECONDS:
717
+ violations.append(
718
+ f"ttl_seconds must be between 1 and {MAX_TTL_SECONDS:,} seconds "
719
+ f"(got {ttl_seconds:,}); omit it for an entry that never expires"
720
+ )
721
+ examples.append("ttl_seconds=86400")
722
+ if value and value.strip():
723
+ actual = _entry_size_bytes(value.strip(), namespace, key, metadata)
724
+ cap = _max_entry_bytes()
725
+ if actual > cap:
726
+ violations.append(_entry_size_violation(actual, cap))
506
727
  return violations, examples
507
728
 
508
729
 
@@ -522,7 +743,11 @@ def _format_store_violations(violations: list[str], examples: list[str]) -> str:
522
743
  "by database trigger. Returns the entry ID and status. "
523
744
  "metadata is a JSON object encoded as a STRING (not an object) and value "
524
745
  "must be non-empty; every invalid argument is reported together in one "
525
- f"message. Example: {METADATA_EXAMPLE}",
746
+ "message. Entries larger than PANTHEON_MEMORY_MAX_ENTRY_BYTES (default "
747
+ "64 KiB serialized) are rejected, never truncated. Pass ttl_seconds to make "
748
+ "the entry expire: it is then hidden from memory_search (default) until "
749
+ "memory_forget(expired_only=True) removes it. "
750
+ f"Example: {METADATA_EXAMPLE}",
526
751
  )
527
752
  def memory_store(
528
753
  value: str = "",
@@ -537,6 +762,7 @@ def memory_store(
537
762
  'Example: \'{"type": "decision", "score": 0.9}\'.',
538
763
  ),
539
764
  ] = "{}",
765
+ ttl_seconds: int | None = None,
540
766
  ) -> dict[str, Any]:
541
767
  """Store a value and index it for FTS5 keyword search.
542
768
 
@@ -545,26 +771,38 @@ def memory_store(
545
771
  namespace: Namespace for isolation (default: "default").
546
772
  key: Optional unique key within namespace.
547
773
  metadata: Optional JSON object encoded as a string.
774
+ ttl_seconds: Optional lifetime in seconds. When set, the entry is
775
+ hidden from search after that moment; omit for no expiry.
548
776
 
549
777
  Returns:
550
- Dict with id, namespace, key, status.
778
+ Dict with id, namespace, key, status, and expires_at (None when the
779
+ entry does not expire).
551
780
  """
552
- violations, examples = _collect_store_violations(value, metadata)
781
+ violations, examples = _collect_store_violations(
782
+ value, metadata, namespace, key, ttl_seconds
783
+ )
553
784
  if violations:
554
785
  return {"error": _format_store_violations(violations, examples)}
555
786
 
556
787
  value = value.strip()
557
788
  db = _get_conn()
558
789
  now = _now_iso()
790
+ expires_at = (
791
+ None
792
+ if ttl_seconds is None
793
+ else time.strftime(
794
+ "%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() + int(ttl_seconds))
795
+ )
796
+ )
559
797
 
560
798
  metadata_str = metadata if metadata else "{}"
561
799
 
562
800
  try:
563
801
  cur = db.execute(
564
802
  """INSERT INTO memories (namespace, key, value, metadata,
565
- created_at, updated_at)
566
- VALUES (?, ?, ?, ?, ?, ?)""",
567
- [namespace, key, value, metadata_str, now, now],
803
+ created_at, updated_at, expires_at)
804
+ VALUES (?, ?, ?, ?, ?, ?, ?)""",
805
+ [namespace, key, value, metadata_str, now, now, expires_at],
568
806
  )
569
807
  entry_id = cur.lastrowid
570
808
  db.commit()
@@ -575,7 +813,13 @@ def memory_store(
575
813
  db.rollback()
576
814
  return {"error": f"Failed to store memory: {e}"}
577
815
 
578
- return {"id": entry_id, "namespace": namespace, "key": key, "status": "stored"}
816
+ return {
817
+ "id": entry_id,
818
+ "namespace": namespace,
819
+ "key": key,
820
+ "status": "stored",
821
+ "expires_at": expires_at,
822
+ }
579
823
 
580
824
 
581
825
  @mcp.tool(
@@ -584,14 +828,18 @@ def memory_store(
584
828
  "prefix-matched, so a query must share a token with the stored text — "
585
829
  "there is no semantic/vector retrieval. Optional decay_days applies a "
586
830
  "freshness half-life (2^(-days/decay_days)) so recent entries rank "
587
- "higher; default None keeps the raw BM25 order.",
831
+ "higher; default None keeps the raw BM25 order. Expired entries "
832
+ "(stored with ttl_seconds) are excluded by default; pass "
833
+ "include_expired=True to see them. An empty result means "
834
+ "nothing matched; an error means the memory store could not be read.",
588
835
  )
589
836
  def memory_search(
590
837
  query: str,
591
838
  namespace: str | None = None,
592
839
  top_k: int = 5,
593
840
  decay_days: float | None = None,
594
- ) -> list[dict[str, Any]]:
841
+ include_expired: bool = False,
842
+ ) -> list[dict[str, Any]] | MemorySearchError:
595
843
  """Search memories with FTS5 BM25.
596
844
 
597
845
  Args:
@@ -601,86 +849,97 @@ def memory_search(
601
849
  decay_days: Optional freshness half-life in days. When set, BM25
602
850
  scores are multiplied by ``2^(-days_since_created/decay_days)``
603
851
  so older entries rank lower. Default None = no decay.
852
+ include_expired: Include entries whose ``expires_at`` has passed.
853
+ Default False, so an expired entry stops appearing in search
854
+ results without any row being deleted.
604
855
 
605
856
  Returns:
606
857
  List of memory entries with a ``score`` (BM25, higher is better,
607
- freshness-decayed when ``decay_days`` is set) and parsed metadata.
858
+ freshness-decayed when ``decay_days`` is set) and parsed metadata, or a
859
+ typed error when the memory store cannot be read.
608
860
  """
609
861
  if not query or not query.strip():
610
862
  return []
611
863
 
612
- top_k = max(1, min(50, int(top_k)))
613
- db = _get_conn()
614
864
  fts_query = _build_fts_query(query)
615
865
  if not fts_query:
616
866
  return []
617
867
 
868
+ top_k = max(1, min(50, int(top_k)))
618
869
  try:
619
- params: list[Any] = [fts_query]
620
- namespace_clause = ""
621
- if namespace:
622
- namespace_clause = " AND namespace = ?"
623
- params.append(namespace)
624
- # Over-fetch 2x: freshness decay can promote a candidate that BM25
625
- # ranked outside top_k, and ranking happens after the fetch.
626
- params.append(top_k * 2)
627
- # ``rank`` is BM25 negated by FTS5 (lower = better), so -rank is the
628
- # relevance score. It is selected explicitly so the value is available
629
- # for scoring rather than only for ordering.
630
- rows = db.execute(
631
- f"""SELECT rowid, -rank AS bm25 FROM memories_fts
632
- WHERE memories_fts MATCH ?{namespace_clause}
633
- ORDER BY rank LIMIT ?""",
634
- params,
635
- ).fetchall()
636
- hits = [(r["rowid"], r["bm25"]) for r in rows]
870
+ db = _get_conn()
637
871
  except Exception:
638
- return []
639
-
640
- if not hits:
641
- return []
872
+ _LOGGER.warning("memory_search failed: memory database could not be opened")
873
+ return {
874
+ "error": {
875
+ "type": "DatabaseUnavailableError",
876
+ "message": (
877
+ "Memory database could not be opened. Check its configured "
878
+ "location and permissions, then retry."
879
+ ),
880
+ }
881
+ }
642
882
 
643
- candidate_ids = [doc_id for doc_id, _ in hits]
644
- created_at_map = (
645
- _fetch_created_at_map(db, candidate_ids)
646
- if decay_days is not None and decay_days > 0
647
- else {}
648
- )
649
- ranked = _score_hits(hits, top_k, created_at_map, decay_days)
883
+ try:
884
+ # Over-fetch 2x: freshness decay can promote a candidate that BM25
885
+ # ranked outside top_k, and ranking happens after the fetch.
886
+ hits = _search_candidates(db, fts_query, namespace, top_k * 2, include_expired)
887
+ if not hits:
888
+ return []
650
889
 
651
- results: list[dict[str, Any]] = []
652
- if ranked:
653
- # 5. Fetch full entries
654
- id_list = [doc_id for doc_id, _ in ranked]
655
- score_map = {doc_id: score for doc_id, score in ranked}
890
+ candidate_ids = [doc_id for doc_id, _ in hits]
891
+ created_at_map = (
892
+ _fetch_created_at_map(db, candidate_ids)
893
+ if decay_days is not None and decay_days > 0
894
+ else {}
895
+ )
896
+ ranked = _score_hits(hits, top_k, created_at_map, decay_days)
656
897
 
657
- try:
898
+ results: list[dict[str, Any]] = []
899
+ if ranked:
900
+ # 5. Fetch full entries
901
+ id_list = [doc_id for doc_id, _ in ranked]
902
+ score_map = {doc_id: score for doc_id, score in ranked}
658
903
  placeholders = ",".join("?" * len(id_list))
659
904
  rows = db.execute(
660
- f"""SELECT id, namespace, key, value, metadata, created_at
905
+ f"""SELECT id, namespace, key, value, metadata, created_at,
906
+ expires_at
661
907
  FROM memories WHERE id IN ({placeholders})""",
662
908
  id_list,
663
909
  ).fetchall()
664
- except Exception:
665
- return []
666
910
 
667
- # Preserve ranking order
668
- row_map = {r["id"]: r for r in rows}
669
- for doc_id in id_list:
670
- row = row_map.get(doc_id)
671
- if row is None:
672
- continue
673
- entry = dict(row)
674
- entry = _parse_metadata(entry)
675
- entry["score"] = round(score_map.get(doc_id, 0.0), 4)
676
- results.append(entry)
911
+ # Preserve ranking order
912
+ row_map = {r["id"]: r for r in rows}
913
+ for doc_id in id_list:
914
+ row = row_map.get(doc_id)
915
+ if row is None:
916
+ continue
917
+ entry = dict(row)
918
+ entry = _parse_metadata(entry)
919
+ entry["score"] = round(score_map.get(doc_id, 0.0), 4)
920
+ results.append(entry)
921
+ except Exception:
922
+ _LOGGER.warning("memory_search failed: FTS or stored-entry read failed")
923
+ return {
924
+ "error": {
925
+ "type": "MemorySearchError",
926
+ "message": (
927
+ "Memory search failed while reading the SQLite FTS index "
928
+ "or stored entries. Check the memory store and FTS index, "
929
+ "then retry."
930
+ ),
931
+ }
932
+ }
677
933
 
678
934
  return results
679
935
 
680
936
 
681
937
  @mcp.tool(
682
938
  description="Recall a specific memory entry by its key within a namespace. "
683
- "Returns the full entry including parsed metadata.",
939
+ "Returns the full entry including parsed metadata and expires_at. Recall "
940
+ "ignores expiry: an expired entry is still returned by exact key until "
941
+ "memory_forget(expired_only=True) removes it, because None would be "
942
+ "indistinguishable from an entry that never existed.",
684
943
  )
685
944
  def memory_recall(
686
945
  key: str,
@@ -693,15 +952,15 @@ def memory_recall(
693
952
  namespace: Namespace scope (default: "default").
694
953
 
695
954
  Returns:
696
- The memory entry dict, or None if not found.
955
+ The memory entry dict (including ``expires_at``), or None if not found.
697
956
  """
698
957
  if not key or not key.strip():
699
958
  return None
700
959
 
701
960
  db = _get_conn()
702
961
  row = db.execute(
703
- "SELECT id, namespace, key, value, metadata, created_at, updated_at "
704
- "FROM memories WHERE namespace = ? AND key = ?",
962
+ "SELECT id, namespace, key, value, metadata, created_at, updated_at, "
963
+ "expires_at FROM memories WHERE namespace = ? AND key = ?",
705
964
  [namespace, key.strip()],
706
965
  ).fetchone()
707
966
 
@@ -712,28 +971,70 @@ def memory_recall(
712
971
  return _parse_metadata(entry)
713
972
 
714
973
 
974
+ def _purge_expired(db: sqlite3.Connection) -> dict[str, Any]:
975
+ """Delete every entry whose TTL has passed, across all namespaces.
976
+
977
+ Expiry alone never deletes a row: search merely hides it. This is the
978
+ explicit reclamation step, and it is the only code path that removes
979
+ expired entries. Entries without a TTL are never touched.
980
+
981
+ Args:
982
+ db: Active SQLite connection.
983
+
984
+ Returns:
985
+ Dict with ``deleted``, ``purged`` (row count), and ``expired_only``.
986
+ """
987
+ try:
988
+ cur = db.execute(
989
+ "DELETE FROM memories WHERE expires_at IS NOT NULL AND expires_at <= ?",
990
+ [_now_iso()],
991
+ )
992
+ purged = cur.rowcount
993
+ db.commit()
994
+ except Exception as e:
995
+ db.rollback()
996
+ return {"error": f"Failed to purge expired entries: {e}"}
997
+ return {"deleted": purged > 0, "purged": purged, "expired_only": True}
998
+
999
+
715
1000
  @mcp.tool(
716
- description="Delete a memory entry by ID or by key. "
1001
+ description="Delete a memory entry by ID or by key, or remove every "
1002
+ "expired entry with expired_only=True. Expiry only hides entries from "
1003
+ "search; this is the explicit way to reclaim the space. "
717
1004
  "The FTS5 index entry is removed automatically by trigger.",
718
1005
  )
719
1006
  def memory_forget(
720
1007
  id: int | None = None,
721
1008
  key: str | None = None,
722
1009
  namespace: str = "default",
1010
+ expired_only: bool = False,
723
1011
  ) -> dict[str, Any]:
724
1012
  """Delete a memory entry and its FTS5 index entry.
725
1013
 
726
1014
  Provide either ``id`` (exact rowid) or ``key`` (within namespace)
727
- to identify the entry. The FTS sync trigger handles index cleanup.
1015
+ to identify the entry, or ``expired_only=True`` to delete every entry
1016
+ whose TTL has passed. The FTS sync trigger handles index cleanup.
728
1017
 
729
1018
  Args:
730
1019
  id: Exact row ID of the entry to delete.
731
1020
  key: Key of the entry to delete (requires namespace).
732
1021
  namespace: Namespace scope when using key (default: "default").
1022
+ expired_only: Delete all entries whose ``expires_at`` has passed,
1023
+ across namespaces. Cannot be combined with id or key. Entries
1024
+ without a TTL are never touched.
733
1025
 
734
1026
  Returns:
735
- Dict with deleted status and entry identifier.
1027
+ Dict with deleted status and entry identifier, or with ``purged`` (the
1028
+ number of expired entries removed) when ``expired_only`` is used.
736
1029
  """
1030
+ if expired_only:
1031
+ if id is not None or (key and key.strip()):
1032
+ return {
1033
+ "error": "expired_only cannot be combined with id or key; call "
1034
+ "it alone to purge every expired entry"
1035
+ }
1036
+ return _purge_expired(_get_conn())
1037
+
737
1038
  if id is not None:
738
1039
  identifier = id
739
1040
  col = "id"
@@ -800,7 +1101,7 @@ def memory_list(
800
1101
 
801
1102
  try:
802
1103
  rows = db.execute(
803
- f"SELECT id, namespace, key, value, metadata, created_at "
1104
+ f"SELECT id, namespace, key, value, metadata, created_at, expires_at "
804
1105
  f"FROM memories WHERE {where} ORDER BY created_at DESC LIMIT ?",
805
1106
  [*params, limit],
806
1107
  ).fetchall()
@@ -817,15 +1118,21 @@ def memory_list(
817
1118
 
818
1119
  @mcp.tool(
819
1120
  description="Memory database statistics: total entries, per-namespace "
820
- "breakdown, and file size on disk.",
1121
+ "breakdown, file size on disk, plus entry-payload size: total_bytes, the "
1122
+ "per-entry cap and warning threshold in bytes, the count of entries over "
1123
+ "the warning threshold, and the largest entries with namespace/key/size.",
821
1124
  )
822
1125
  def memory_stats() -> dict[str, Any]:
823
1126
  """Return aggregate statistics about the memory database.
824
1127
 
825
- Includes total count, namespace breakdown, and file size on disk.
1128
+ Includes total count, namespace breakdown, file size on disk, and payload
1129
+ size accounting so an operator can see what to prune before the store grows
1130
+ unbounded: the entry cap in force, how much of the store is payload, which
1131
+ entries are largest, and how many are already over the warning threshold
1132
+ (half the cap).
826
1133
 
827
1134
  Returns:
828
- Dict with count, namespaces, and storage info.
1135
+ Dict with count, namespaces, storage info, and size accounting.
829
1136
  """
830
1137
  db = _get_conn()
831
1138
 
@@ -849,6 +1156,39 @@ def memory_stats() -> dict[str, Any]:
849
1156
  except Exception:
850
1157
  stats["namespaces"] = []
851
1158
 
1159
+ cap = _max_entry_bytes()
1160
+ warning_threshold = max(1, cap // 2)
1161
+ stats["max_entry_bytes"] = cap
1162
+ stats["warning_threshold_bytes"] = warning_threshold
1163
+
1164
+ try:
1165
+ stats["total_bytes"] = db.execute(
1166
+ f"SELECT coalesce(sum({_ENTRY_BYTES_SQL}), 0) AS b FROM memories"
1167
+ ).fetchone()["b"]
1168
+ except Exception:
1169
+ stats["total_bytes"] = 0
1170
+
1171
+ try:
1172
+ over_rows = db.execute(
1173
+ f"SELECT COUNT(*) AS c FROM memories WHERE ({_ENTRY_BYTES_SQL}) > ?",
1174
+ [warning_threshold],
1175
+ ).fetchone()
1176
+ stats["oversized_entries"] = over_rows["c"]
1177
+ except Exception:
1178
+ stats["oversized_entries"] = 0
1179
+
1180
+ try:
1181
+ largest = db.execute(
1182
+ f"SELECT namespace, key, ({_ENTRY_BYTES_SQL}) AS bytes FROM memories "
1183
+ "ORDER BY bytes DESC, id ASC LIMIT 5"
1184
+ ).fetchall()
1185
+ stats["largest_entries"] = [
1186
+ {"namespace": r["namespace"], "key": r["key"], "bytes": r["bytes"]}
1187
+ for r in largest
1188
+ ]
1189
+ except Exception:
1190
+ stats["largest_entries"] = []
1191
+
852
1192
  try:
853
1193
  db_size = DB_PATH.stat().st_size if DB_PATH.exists() else 0
854
1194
  stats["db_size_bytes"] = db_size
@@ -870,8 +1210,8 @@ def memory_stats() -> dict[str, Any]:
870
1210
 
871
1211
 
872
1212
  @mcp.tool(
873
- description="Index codebase files incrementally (hash-based skip). "
874
- "Parses Python (ast) and TypeScript (regex) to build knowledge graph.",
1213
+ description="Index supported files inside the host-bound project root only. "
1214
+ "Parses Python (ast) and TypeScript (regex) into the shared Memory DB.",
875
1215
  )
876
1216
  def code_index(
877
1217
  path: str | None = None,
@@ -880,7 +1220,7 @@ def code_index(
880
1220
  """Index code files into knowledge graph.
881
1221
 
882
1222
  Args:
883
- path: File or directory to index; None = cwd.
1223
+ path: File or directory within the trusted project root; None = project root.
884
1224
  force: Re-parse even if hash unchanged.
885
1225
 
886
1226
  Returns:
@@ -888,8 +1228,18 @@ def code_index(
888
1228
  """
889
1229
  if _codemap is None:
890
1230
  return {"error": "codemap module not available"}
1231
+ project_root = trusted_project_root()
1232
+ if project_root is None:
1233
+ return {
1234
+ "error": (
1235
+ "Trusted project root unavailable; code_index requires the MCP "
1236
+ "host to set PANTHEON_PROJECT to an absolute project directory"
1237
+ ),
1238
+ "indexed": 0,
1239
+ "skipped": 0,
1240
+ }
891
1241
  db = _get_conn()
892
- return _codemap.code_index(db, path, force)
1242
+ return _codemap.code_index(db, path, force, project_root=project_root)
893
1243
 
894
1244
 
895
1245
  @mcp.tool(