pantheon-opencode 1.6.0-beta.8 → 1.6.0
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.
- package/AGENTS.global.md +118 -0
- package/AGENTS.md +18 -168
- package/CHANGELOG.md +126 -346
- package/README.md +83 -608
- package/README.pt-BR.md +120 -345
- package/bin/pantheon-init.mjs +366 -132
- package/commands/pantheon-audit.md +7 -1
- package/commands/pantheon-consolidate.md +1 -1
- package/commands/pantheon-deepwork.md +14 -3
- package/commands/pantheon-focus.md +17 -0
- package/commands/pantheon-vision.md +61 -12
- package/package.json +19 -11
- package/plugin.json +1 -1
- package/pyproject.toml +6 -2
- package/scripts/_pantheon_paths.py +24 -0
- package/scripts/build-agents-md.mjs +368 -69
- package/scripts/changelog-merge.mjs +161 -0
- package/scripts/check-plugin-v2-coverage.mjs +11 -8
- package/scripts/docs-check-changelog.mjs +204 -0
- package/scripts/docs-link-check.mjs +314 -0
- package/scripts/docs-media.mjs +157 -0
- package/scripts/doctor.mjs +828 -40
- package/scripts/install/agents-md.mjs +2 -2
- package/scripts/install/backup.mjs +648 -0
- package/scripts/install/cli-ui.mjs +303 -72
- package/scripts/install/component-selection.mjs +61 -0
- package/scripts/install/config-migration.mjs +583 -27
- package/scripts/install/exit-codes.mjs +26 -0
- package/scripts/install/file-inventory.mjs +555 -0
- package/scripts/install/health-check.mjs +31 -25
- package/scripts/install/interactive.mjs +78 -383
- package/scripts/install/migrate.mjs +49 -25
- package/scripts/install/model-picker.mjs +218 -250
- package/scripts/install/opencode-version.mjs +83 -21
- package/scripts/install/opencode.mjs +1465 -180
- package/scripts/install/plan-artifact.mjs +517 -0
- package/scripts/install/plan.mjs +475 -0
- package/scripts/install/plugin.mjs +251 -30
- package/scripts/install/prompt-result.mjs +2 -0
- package/scripts/install/shared.mjs +256 -99
- package/scripts/install/state.mjs +63 -8
- package/scripts/install/strings.mjs +60 -4
- package/scripts/install/venv.mjs +90 -47
- package/scripts/install/verify.mjs +128 -0
- package/scripts/install/vision-prompt.mjs +173 -0
- package/scripts/install-mcp.mjs +2 -2
- package/scripts/manifest-inventory.mjs +49 -3
- package/scripts/mcp_persistence.py +1535 -1050
- package/scripts/memory_mcp.py +12 -843
- package/scripts/node-engine-policy.mjs +85 -0
- package/scripts/package-evidence.mjs +10 -2
- package/scripts/postinstall.mjs +26 -26
- package/scripts/probe-pantheon-cost.mjs +118 -19
- package/scripts/prune.mjs +9 -3
- package/scripts/reconcile.mjs +325 -0
- package/scripts/release-gates.mjs +682 -0
- package/scripts/restore.mjs +222 -0
- package/scripts/run-node-tests.mjs +24 -8
- package/scripts/sync-artifacts.mjs +20 -7
- package/scripts/sync-tui.mjs +29 -4
- package/scripts/test-opencode-v2-sandbox.sh +36 -123
- package/scripts/uninstall.mjs +369 -34
- package/scripts/update.mjs +164 -0
- package/scripts/validate-node-engine-policy.mjs +13 -0
- package/scripts/version-check.mjs +34 -1
- package/scripts/versioning.mjs +23 -3
- package/scripts/vision-status.mjs +682 -0
- package/skills-lock.json +8 -8
- package/src/agents/aphrodite.md +13 -10
- package/src/agents/apollo.md +4 -5
- package/src/agents/athena.md +74 -46
- package/src/agents/demeter.md +10 -7
- package/src/agents/gaia.md +0 -1
- package/src/agents/hephaestus.md +4 -3
- package/src/agents/hermes.md +10 -9
- package/src/agents/iris.md +6 -1
- package/src/agents/mnemosyne.md +14 -15
- package/src/agents/nyx.md +4 -4
- package/src/agents/prometheus.md +12 -11
- package/src/agents/talos.md +6 -0
- package/src/agents/zeus.md +84 -56
- package/src/instructions/agent-return-format.instructions.md +12 -41
- package/src/instructions/memory-protocol.instructions.md +5 -11
- package/src/instructions/test-economy.instructions.md +12 -0
- package/src/instructions/yagni.instructions.md +6 -15
- package/src/instructions/zeus-anti-stall.instructions.md +6 -6
- package/src/instructions/zeus-communication-rules.instructions.md +6 -6
- package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
- package/src/instructions/zeus-memory-operations.instructions.md +13 -7
- package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
- package/src/mcp/_pantheon_paths.py +24 -0
- package/src/mcp/mcp_codemap_module.py +86 -18
- package/src/mcp/mcp_persistence.py +1535 -1050
- package/src/mcp/memory_mcp.py +444 -94
- package/src/mcp/pantheon_vision.py +285 -41
- package/src/mcp/requirements-mcp.txt +5 -0
- package/src/pantheon/context-pruner.ts +541 -0
- package/src/pantheon/cost-command.ts +814 -60
- package/src/pantheon/goal-loop.ts +11 -8
- package/src/pantheon/memory-context.ts +1017 -0
- package/src/pantheon/model-agents.ts +19 -0
- package/src/pantheon/model-command.ts +218 -56
- package/src/pantheon/model-pricing.ts +536 -0
- package/src/pantheon/presets.mjs +2 -0
- package/src/pantheon/task-result-guard.ts +50 -14
- package/src/pantheon/v2-bounded-read.ts +640 -0
- package/src/pantheon/v2-delegation-enforce.ts +133 -6
- package/src/pantheon/v2-execute-after.ts +135 -24
- package/src/pantheon/v2-model-overrides.ts +275 -0
- package/src/pantheon/v2-tools.ts +89 -35
- package/src/pantheon/v2-unsupported.mjs +2 -3
- package/src/pantheon/v2-vision.ts +622 -0
- package/src/pantheon/vision-local.ts +531 -0
- package/src/pantheon/vision.ts +1160 -115
- package/src/plugin-v2.ts +654 -162
- package/src/plugin.ts +15 -11
- package/src/plugins/tui/dist/tui-v2.d.ts +1036 -0
- package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -0
- package/src/plugins/tui/dist/tui-v2.js +3808 -0
- package/src/plugins/tui/dist/tui-v2.js.map +1 -0
- package/src/plugins/tui/dist/tui.js +4 -4
- package/src/plugins/tui/index-v2.ts +6 -0
- package/src/plugins/tui/package-lock.json +5416 -1297
- package/src/plugins/tui/package.json +14 -10
- package/src/plugins/tui/src/index-v2.tsx +4372 -0
- package/src/plugins/tui/src/index.tsx +3 -3
- package/src/plugins/tui/src/opencode-v2.d.ts +13 -0
- package/src/plugins/tui/tsconfig.typecheck.json +5 -0
- package/src/plugins/tui/tsdown.config.ts +2 -2
- package/src/plugins/tui/tui-v2.ts +2 -0
- package/src/plugins/tui/tui.ts +3 -0
- package/src/routing.yml +50 -5
- package/src/skills/agent-coordination/SKILL.md +7 -2
- package/src/skills/artifact-management/SKILL.md +5 -1
- package/src/skills/auto-continue/SKILL.md +14 -6
- package/src/skills/codemap/SKILL.md +1 -1
- package/src/skills/memory-bank/SKILL.md +21 -13
- package/src/skills/session-goal/SKILL.md +14 -15
- package/src/skills/spec-driven-development/SKILL.md +3 -1
- package/src/skills/worktrees/SKILL.md +30 -11
- package/scripts/probe-context-rehydrate.mjs +0 -263
package/src/mcp/memory_mcp.py
CHANGED
|
@@ -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
|
|
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 ``""``
|
|
315
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
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(
|
|
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
|
-
|
|
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(
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
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
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
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
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
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
|
-
|
|
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
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
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
|
|
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,
|
|
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,
|
|
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
|
|
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
|
|
874
|
-
"Parses Python (ast) and TypeScript (regex)
|
|
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
|
|
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(
|