mintmory-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,59 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.pyo
5
+ .venv/
6
+ .env
7
+ *.egg-info/
8
+ dist/
9
+ build/
10
+ .coverage
11
+ .pytest_cache/
12
+ htmlcov/
13
+ .mypy_cache/
14
+ .ruff_cache/
15
+
16
+ # uv
17
+ # uv.lock IS committed (MM-44): the Dockerfile/CI build with `uv sync --frozen`
18
+ # for reproducible, supply-chain-pinned images. Do not re-ignore it.
19
+ .uv/
20
+
21
+ # SQLite databases (dev only — test DBs should not be committed)
22
+ *.db
23
+ *.sqlite
24
+ *.sqlite3
25
+ !tests/fixtures/*.db
26
+
27
+ # Embeddings cache
28
+ .embeddings_cache/
29
+ *.index
30
+ *.npy
31
+
32
+ # IDE
33
+ .idea/
34
+ .vscode/
35
+ *.swp
36
+ *.swo
37
+
38
+ # OS
39
+ .DS_Store
40
+ Thumbs.db
41
+
42
+ # Secrets
43
+ .env.local
44
+ .env.production
45
+ *.key
46
+ *.pem
47
+
48
+ # Firecrawl local cache (CLI scrape/crawl output)
49
+ .firecrawl/
50
+
51
+ # Docs build
52
+ docs/_build/
53
+ site/
54
+
55
+ # Local test corpus (verbatim internal data) and scratch DBs — keep out of git history
56
+ scripts/corpus_parts/
57
+ *.db
58
+ *.db-wal
59
+ *.db-shm
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WeLikeCode
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,34 @@
1
+ Metadata-Version: 2.4
2
+ Name: mintmory-mcp
3
+ Version: 0.1.0
4
+ Summary: MintMory MCP server — stdio and SSE transports via fastmcp
5
+ Project-URL: Homepage, https://github.com/WeLikeCode/mint-mory
6
+ Project-URL: Repository, https://github.com/WeLikeCode/mint-mory
7
+ Project-URL: Issues, https://github.com/WeLikeCode/mint-mory/issues
8
+ Author: WeLikeCode
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,llm,mcp,memory,sqlite,vector-search
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.12
20
+ Requires-Dist: anthropic>=0.35
21
+ Requires-Dist: fastmcp>=2.3
22
+ Requires-Dist: mcp>=1.6
23
+ Requires-Dist: mintmory-core~=0.1.0
24
+ Requires-Dist: structlog>=24.4
25
+ Description-Content-Type: text/markdown
26
+
27
+ # mintmory-mcp
28
+
29
+ MCP server for [MintMory](https://github.com/WeLikeCode/mint-mory) — exposes
30
+ the typed agent-memory system over the Model Context Protocol (stdio/SSE via
31
+ fastmcp). Entry points: `mintmory-mcp`, `mintmory-history-mcp`.
32
+
33
+ Most users want the umbrella package instead: `pip install "mintmory[mcp]"`.
34
+ MIT licensed.
@@ -0,0 +1,8 @@
1
+ # mintmory-mcp
2
+
3
+ MCP server for [MintMory](https://github.com/WeLikeCode/mint-mory) — exposes
4
+ the typed agent-memory system over the Model Context Protocol (stdio/SSE via
5
+ fastmcp). Entry points: `mintmory-mcp`, `mintmory-history-mcp`.
6
+
7
+ Most users want the umbrella package instead: `pip install "mintmory[mcp]"`.
8
+ MIT licensed.
@@ -0,0 +1,46 @@
1
+ [project]
2
+ name = "mintmory-mcp"
3
+ version = "0.1.0"
4
+ description = "MintMory MCP server — stdio and SSE transports via fastmcp"
5
+ requires-python = ">=3.12"
6
+ readme = "README.md"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "WeLikeCode" }]
10
+ keywords = ["memory", "llm", "agents", "mcp", "sqlite", "vector-search"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Intended Audience :: Developers",
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3.12",
16
+ "Programming Language :: Python :: 3.13",
17
+ "Topic :: Software Development :: Libraries :: Python Modules",
18
+ "Typing :: Typed",
19
+ ]
20
+
21
+ dependencies = [
22
+ "mintmory-core~=0.1.0",
23
+ "fastmcp>=2.3",
24
+ "mcp>=1.6",
25
+ "anthropic>=0.35", # LLM passive self-assessment
26
+ "structlog>=24.4",
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/WeLikeCode/mint-mory"
31
+ Repository = "https://github.com/WeLikeCode/mint-mory"
32
+ Issues = "https://github.com/WeLikeCode/mint-mory/issues"
33
+
34
+ [build-system]
35
+ requires = ["hatchling>=1.27"]
36
+ build-backend = "hatchling.build"
37
+
38
+ [tool.hatch.build.targets.wheel]
39
+ packages = ["src/mintmory"]
40
+
41
+ [tool.uv.sources]
42
+ mintmory-core = { workspace = true }
43
+
44
+ [project.scripts]
45
+ mintmory-mcp = "mintmory.mcp.server:main"
46
+ mintmory-history-mcp = "mintmory.mcp.history_server:main"
@@ -0,0 +1 @@
1
+ """mintmory-mcp: FastMCP server providing all MintMory tools over stdio and SSE."""
@@ -0,0 +1,101 @@
1
+ """
2
+ Schema helper for the mintmory://schema MCP resource (MM-40).
3
+
4
+ Provides a curated one-line description per MemoryCategory / ConceptLinkType /
5
+ MemorySource value. Names are always iterated from the live enums; descriptions
6
+ are kept in the CATEGORY_DESCRIPTIONS / LINK_TYPE_DESCRIPTIONS / SOURCE_DESCRIPTIONS
7
+ maps below. A coverage guard raises KeyError immediately if a new enum value is
8
+ added without a corresponding description (caught by the unit-test suite before CI).
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from typing import Any
14
+
15
+ from mintmory.core.types import ConceptLinkType, MemoryCategory, MemoryRecord, MemorySource
16
+
17
+ # ---------------------------------------------------------------------------
18
+ # Curated description maps — copied from inline comments in core/types.py
19
+ # ---------------------------------------------------------------------------
20
+
21
+ CATEGORY_DESCRIPTIONS: dict[str, str] = {
22
+ "identity": "Persistent facts about the user/agent",
23
+ "preference": "Stated or inferred preferences",
24
+ "skill": "How to do something; procedures, tools, recipes",
25
+ "context": "Current working context, active project state",
26
+ "fact": "World-state facts, configuration values, URLs",
27
+ "episodic": "Something that happened in a specific session",
28
+ "temporal": "Time-bounded fact with explicit validity window",
29
+ "relationship": "A typed link between two entities (stored as ConceptLink)",
30
+ }
31
+
32
+ LINK_TYPE_DESCRIPTIONS: dict[str, str] = {
33
+ "relates_to": "General connection, no specific direction (symmetric)",
34
+ "contradicts": "Cannot both be true (symmetric)",
35
+ "refines": "B adds specificity to A; inverse: generalizes",
36
+ "supersedes": "B replaces A completely; inverse: precedes",
37
+ "enables": "A made B possible; inverse: enabled_by",
38
+ "depends_on": "A requires B; inverse: supports",
39
+ "similar_to": "A is like B (symmetric)",
40
+ "part_of": "A is contained in B; inverse: contains",
41
+ "uses": "A actively uses B; inverse: used_by",
42
+ "before": "A occurred before B (temporal); inverse: after",
43
+ "valid_until": "A is true until time T (encoded in target metadata)",
44
+ "annotates": "A (a note) annotates B (the item it is about); inverse: annotated_by",
45
+ }
46
+
47
+ SOURCE_DESCRIPTIONS: dict[str, str] = {
48
+ "user": "Explicitly provided by the human user",
49
+ "agent": "Inferred or generated by the AI agent",
50
+ "document": "Extracted from an indexed document or file",
51
+ "inference": "Derived by the system during processing",
52
+ }
53
+
54
+
55
+ # ---------------------------------------------------------------------------
56
+ # Schema builder
57
+ # ---------------------------------------------------------------------------
58
+
59
+
60
+ def _describe(value: str, table: dict[str, str], kind: str) -> str:
61
+ """Look up a curated description; fail with a clear message if one is missing.
62
+
63
+ Coverage guard: adding an enum value without a description here fails loudly
64
+ (and the unit tests trip) instead of producing a cryptic bare KeyError.
65
+ """
66
+ try:
67
+ return table[value]
68
+ except KeyError as exc:
69
+ raise KeyError(
70
+ f"{kind} value {value!r} has no description in mcp/_schema.py — add one."
71
+ ) from exc
72
+
73
+
74
+ def build_schema() -> dict[str, Any]:
75
+ """Build the mintmory://schema resource payload.
76
+
77
+ Iterates the live enums for names and looks up the curated descriptions.
78
+ Raises KeyError (with a clear message) if any enum value is missing a
79
+ description (coverage guard).
80
+ """
81
+ categories: list[dict[str, str]] = [
82
+ {"value": cat.value, "description": _describe(cat.value, CATEGORY_DESCRIPTIONS, "category")}
83
+ for cat in MemoryCategory
84
+ ]
85
+ link_types: list[dict[str, str]] = [
86
+ {"value": lt.value, "description": _describe(lt.value, LINK_TYPE_DESCRIPTIONS, "link_type")}
87
+ for lt in ConceptLinkType
88
+ ]
89
+ sources: list[dict[str, str]] = [
90
+ {"value": s.value, "description": _describe(s.value, SOURCE_DESCRIPTIONS, "source")}
91
+ for s in MemorySource
92
+ ]
93
+
94
+ memory_record_fields: list[str] = list(MemoryRecord.model_fields)
95
+
96
+ return {
97
+ "categories": categories,
98
+ "link_types": link_types,
99
+ "sources": sources,
100
+ "memory_record_fields": memory_record_fields,
101
+ }
@@ -0,0 +1,69 @@
1
+ """
2
+ Concise projection helpers for MCP tool responses (MM-38).
3
+
4
+ Pure functions — no I/O, no model imports. Each helper takes an already-
5
+ serialised dict (from model.model_dump(mode="json") or _shape_row) and returns
6
+ a smaller dict with only the fields an agent needs for browsing/scanning.
7
+
8
+ Use verbosity="full" (default) in every tool when you need the complete body or
9
+ metadata; verbosity="concise" for lightweight passes.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from typing import Any
15
+
16
+ SNIPPET_CHARS = 200
17
+
18
+
19
+ def _snip(text: str, n: int = SNIPPET_CHARS) -> str:
20
+ """Truncate *text* to *n* chars, appending '…' when truncated."""
21
+ return text if len(text) <= n else text[:n].rstrip() + "…"
22
+
23
+
24
+ def concise_memory(rec: dict[str, Any]) -> dict[str, Any]:
25
+ """Project a full MemoryRecord dict to {id, category, snippet, is_note}."""
26
+ return {
27
+ "id": rec["id"],
28
+ "category": rec["category"],
29
+ "snippet": _snip(rec.get("content", "")),
30
+ "is_note": rec.get("is_note", False),
31
+ }
32
+
33
+
34
+ def concise_memory_get(rec: dict[str, Any]) -> dict[str, Any]:
35
+ """Project a full MemoryRecord dict to {id, category, content}.
36
+
37
+ For single-memory fetches the caller *wants* the full content, so we keep
38
+ it — we just drop the scoring/state machinery.
39
+ """
40
+ return {
41
+ "id": rec["id"],
42
+ "category": rec["category"],
43
+ "content": rec.get("content", ""),
44
+ }
45
+
46
+
47
+ def concise_search_response(resp: dict[str, Any]) -> dict[str, Any]:
48
+ """Project a full SearchResponse dict to the concise envelope + lean hits."""
49
+ return {
50
+ "session_id": resp["session_id"],
51
+ "total_found": resp["total_found"],
52
+ "search_around_ids": resp.get("search_around_ids", []),
53
+ "memories": [concise_memory(m) for m in resp["memories"]],
54
+ # notes_on_results: ids only (no nested full records)
55
+ "notes_on_results": {
56
+ k: [n["id"] for n in v] for k, v in resp.get("notes_on_results", {}).items()
57
+ },
58
+ }
59
+
60
+
61
+ def concise_history_row(row: dict[str, Any]) -> dict[str, Any]:
62
+ """Project a full _shape_row dict to {date, repo, kind, title, snippet}."""
63
+ return {
64
+ "date": row["date"],
65
+ "repo": row["repo"],
66
+ "kind": row["kind"],
67
+ "title": row["title"],
68
+ "snippet": _snip(row["summary"]),
69
+ }
@@ -0,0 +1,320 @@
1
+ """
2
+ MintMory History MCP Server — read-only agent-history index.
3
+
4
+ Exposes exactly three tools (NO write/mutate tools):
5
+ history_timeline — dated changelog of sessions in a time window
6
+ history_search — hybrid search across session summaries
7
+ history_stats — counts + date range of indexed sessions
8
+
9
+ Phase-2: rows include segment_index, segment_count, turn_lo, turn_hi, title,
10
+ outcome. history_stats returns total_sessions (distinct session_id) AND
11
+ total_segments (row count). timeline supports group_by_session.
12
+
13
+ The DB is resolved from MINTMORY_HISTORY_DB (or --db), defaulting to
14
+ ~/.mintmory/agent-history.db. At startup the Hermes guard is enforced so
15
+ a misconfigured path (pointing to the working store) fails fast.
16
+
17
+ Transport: stdio (default) or sse (--transport sse --port <N>).
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import json as _json
23
+ import os
24
+ from typing import Any, Literal
25
+
26
+ # FastMCP import — raises ImportError if mintmory-mcp not installed
27
+ try:
28
+ from fastmcp import FastMCP
29
+ except ImportError as e:
30
+ raise ImportError("fastmcp is not installed. Run: uv sync --package mintmory-mcp") from e
31
+
32
+ from mintmory.core.history import query
33
+ from mintmory.core.history.ingest import DEFAULT_HISTORY_DB, _assert_not_working_db
34
+ from mintmory.mcp.concise import concise_history_row
35
+
36
+ # ---------------------------------------------------------------------------
37
+ # Server initialisation
38
+ # ---------------------------------------------------------------------------
39
+
40
+ mcp: FastMCP[Any] = FastMCP(
41
+ "mintmory-history",
42
+ instructions=(
43
+ "READ-ONLY history of past coding sessions (Claude Code / Codex / Kiro). "
44
+ "TIMELINE: use history_timeline for "
45
+ "'what changed/was fixed in the last N days/weeks/months' "
46
+ "— returns newest-first session summaries. "
47
+ 'BROWSING: pass verbosity="concise" for compact '
48
+ "{date, repo, kind, title, snippet} rows "
49
+ 'when scanning many sessions; use the default verbosity="full" '
50
+ "for source_path back-links and all 15 fields. "
51
+ "SEARCH: use history_search for topic recall across all indexed sessions. "
52
+ "STATS: use history_stats to see session/segment counts and date range. "
53
+ "No tool here writes, adds, archives, dreams, or otherwise mutates any store."
54
+ ),
55
+ )
56
+
57
+
58
+ def _db_path() -> str:
59
+ """Return the history DB path from MINTMORY_HISTORY_DB or the default."""
60
+ return os.environ.get("MINTMORY_HISTORY_DB", os.path.expanduser(DEFAULT_HISTORY_DB))
61
+
62
+
63
+ # ---------------------------------------------------------------------------
64
+ # Shared aggregation helper (used by both history_stats tool and
65
+ # mintmory://history/sources resource — MM-40)
66
+ # ---------------------------------------------------------------------------
67
+
68
+
69
+ def _aggregate_stats(db_path: str) -> dict[str, Any]:
70
+ """Aggregate indexed session-summary rows into stats dict.
71
+
72
+ Returns: total_sessions, total_segments, by_collection, by_kind,
73
+ earliest, latest. No per-session content is included.
74
+ """
75
+ store = query._open_history(db_path)
76
+ conn = store.connect()
77
+
78
+ rows = conn.execute(
79
+ "SELECT metadata, valid_from FROM memories "
80
+ "WHERE is_archived = 0 "
81
+ " AND json_extract(metadata, '$.record_type') = 'session_summary' "
82
+ "ORDER BY valid_from ASC"
83
+ ).fetchall()
84
+
85
+ by_collection: dict[str, int] = {}
86
+ by_kind: dict[str, int] = {}
87
+ earliest: str | None = None
88
+ latest: str | None = None
89
+ session_ids: set[str] = set()
90
+
91
+ for row in rows:
92
+ meta: dict[str, Any] = _json.loads(row["metadata"] or "{}")
93
+ coll = meta.get("collection", "unknown")
94
+ knd = meta.get("kind", "unknown")
95
+ by_collection[coll] = by_collection.get(coll, 0) + 1
96
+ by_kind[knd] = by_kind.get(knd, 0) + 1
97
+ vf = (row["valid_from"] or "")[:10] or None
98
+ if vf:
99
+ if earliest is None:
100
+ earliest = vf
101
+ latest = vf
102
+ sid = meta.get("session_id", "")
103
+ if sid:
104
+ session_ids.add(sid)
105
+
106
+ return {
107
+ "total_sessions": len(session_ids),
108
+ "total_segments": len(rows),
109
+ "by_collection": by_collection,
110
+ "by_kind": by_kind,
111
+ "earliest": earliest,
112
+ "latest": latest,
113
+ }
114
+
115
+
116
+ # ---------------------------------------------------------------------------
117
+ # Tools — read-only
118
+ # ---------------------------------------------------------------------------
119
+
120
+
121
+ @mcp.tool()
122
+ def history_timeline(
123
+ since: str = "90d",
124
+ from_date: str | None = None,
125
+ to_date: str | None = None,
126
+ repo: str | None = None,
127
+ kind: str | None = None,
128
+ limit: int = 50,
129
+ group: bool = False,
130
+ verbosity: Literal["full", "concise"] = "full",
131
+ ) -> list[dict[str, Any]]:
132
+ """Dated changelog of agent sessions in a time window (the 'what changed N ago' query).
133
+
134
+ Returns newest-first session summaries from the agent-history index.
135
+ Each full result is a dict with: date, ts_start, agent, collection, repo, branch,
136
+ kind, title, summary, session_id, source_path, segment_index, segment_count,
137
+ turn_lo, turn_hi, outcome.
138
+
139
+ Args:
140
+ since: Relative window like '90d', '8w', '3m', '2y' (default '90d').
141
+ Mutually exclusive with from_date/to_date.
142
+ from_date: ISO start date/datetime (inclusive). Use instead of since.
143
+ to_date: ISO end date/datetime (inclusive). Use instead of since.
144
+ repo: Optional repo-name filter (exact match on metadata.repo).
145
+ kind: Optional kind filter (fix/feature/refactor/…).
146
+ limit: Max rows to return (default 50).
147
+ group: When True, group segments by session (each session's segments
148
+ in ascending segment_index order, groups newest-first).
149
+ verbosity: "full" (default) returns all 15 fields including source_path and
150
+ branch; "concise" returns a compact {date, repo, kind, title, snippet}
151
+ projection for lightweight browsing/scanning.
152
+ """
153
+ # If both from_date and to_date are None but since has its default value,
154
+ # pass since through as-is. If the caller explicitly passes from_date or
155
+ # to_date, suppress the default since so the pair works as from/to only.
156
+ effective_since: str | None = since
157
+ if from_date is not None or to_date is not None:
158
+ effective_since = None
159
+
160
+ rows = query.timeline(
161
+ _db_path(),
162
+ since=effective_since,
163
+ from_iso=from_date,
164
+ to_iso=to_date,
165
+ repo=repo,
166
+ kind=kind,
167
+ limit=limit,
168
+ group_by_session=group,
169
+ )
170
+ if verbosity == "concise":
171
+ return [concise_history_row(r) for r in rows]
172
+ return rows
173
+
174
+
175
+ @mcp.tool()
176
+ def history_search(
177
+ query_text: str,
178
+ repo: str | None = None,
179
+ since: str | None = None,
180
+ limit: int = 10,
181
+ verbosity: Literal["full", "concise"] = "full",
182
+ ) -> list[dict[str, Any]]:
183
+ """Hybrid search across indexed agent session summaries.
184
+
185
+ Searches the full-text + vector index for sessions matching query_text,
186
+ filtered to only session_summary records. Optionally constrained by
187
+ repo and/or a recency window.
188
+
189
+ Args:
190
+ query_text: Natural-language search query.
191
+ repo: Optional repo-name filter (exact match on metadata.repo).
192
+ since: Optional recency window like '90d', '8w', '3m' (no from/to here).
193
+ limit: Max results to return (default 10).
194
+ verbosity: "full" (default) returns the 15-field row shape (same as
195
+ history_timeline); "concise" returns {date, repo, kind, title, snippet}
196
+ for lightweight scanning.
197
+
198
+ Returns:
199
+ List of row dicts in search-rank order (same shape as history_timeline).
200
+ """
201
+ rows = query.search(_db_path(), query_text, repo=repo, since=since, limit=limit)
202
+ if verbosity == "concise":
203
+ return [concise_history_row(r) for r in rows]
204
+ return rows
205
+
206
+
207
+ @mcp.tool()
208
+ def history_stats() -> dict[str, Any]:
209
+ """Counts of indexed sessions and segments by source (collection) and kind, plus date range.
210
+
211
+ Read-only. Returns a dict with:
212
+ total_sessions: distinct session_id count (logical sessions)
213
+ total_segments: total row count (one per segment per session)
214
+ by_collection: {collection_name: count}
215
+ by_kind: {kind: count}
216
+ earliest: ISO date of the oldest segment (or null)
217
+ latest: ISO date of the newest segment (or null)
218
+ """
219
+ return _aggregate_stats(_db_path())
220
+
221
+
222
+ # ---------------------------------------------------------------------------
223
+ # Resources — read-on-demand structured data (MM-40)
224
+ # ---------------------------------------------------------------------------
225
+
226
+
227
+ @mcp.resource("mintmory://history/sources")
228
+ def mintmory_history_sources() -> dict[str, Any]:
229
+ """Indexed collections with per-collection counts and earliest/latest dates.
230
+ No per-session content. Derived from the same aggregation as history_stats."""
231
+ stats = _aggregate_stats(_db_path())
232
+ # Return only the orientation fields — no per-session content
233
+ return {
234
+ "by_collection": stats["by_collection"],
235
+ "total_sessions": stats["total_sessions"],
236
+ "total_segments": stats["total_segments"],
237
+ "earliest": stats["earliest"],
238
+ "latest": stats["latest"],
239
+ }
240
+
241
+
242
+ # ---------------------------------------------------------------------------
243
+ # Prompts — read-only guidance for history tools (MM-40)
244
+ # ---------------------------------------------------------------------------
245
+
246
+
247
+ @mcp.prompt()
248
+ def mintmory_changelog(repo: str = "", since: str = "90d", kind: str = "") -> str:
249
+ """Guidance to query the agent-history changelog for a time window.
250
+
251
+ References only READ tools — this server has no write capability.
252
+
253
+ Args:
254
+ repo: Optional repo name to filter (e.g. 'mintkey'). Empty = all repos.
255
+ since: Relative window like '90d', '8w', '3m', '2y' (default '90d').
256
+ kind: Optional kind filter (fix/feature/refactor/…). Empty = all kinds.
257
+ """
258
+ repo_clause = f", repo={repo!r}" if repo.strip() else ""
259
+ kind_clause = f", kind={kind!r}" if kind.strip() else ""
260
+ return (
261
+ "## Agent-history changelog\n\n"
262
+ "To see what changed, call history_timeline (a READ-only tool):\n\n"
263
+ f" history_timeline(\n"
264
+ f" since={since!r}{repo_clause}{kind_clause},\n"
265
+ f" limit=50,\n"
266
+ f" )\n\n"
267
+ "Results are returned newest-first. Each row has: date, repo, kind, title,\n"
268
+ "summary, session_id, and source_path back-links.\n\n"
269
+ "Tips:\n"
270
+ f" • Use since='{since}' for the last {since} (e.g. '30d'=30 days, '2m'=2 months).\n"
271
+ " • Pass from_date/to_date (ISO strings) instead of since for absolute ranges.\n"
272
+ " • Use history_search(query_text=...) for topic-based recall across all time.\n"
273
+ " • Use history_stats() to see per-collection counts and the date range.\n\n"
274
+ "This server is READ-ONLY: no add, archive, dream, or other mutating tools\n"
275
+ "are available here."
276
+ )
277
+
278
+
279
+ # ---------------------------------------------------------------------------
280
+ # Entry point
281
+ # ---------------------------------------------------------------------------
282
+
283
+
284
+ def main() -> None:
285
+ """Start the mintmory-history MCP server.
286
+
287
+ Enforces the Hermes guard on startup so a misconfigured DB path
288
+ (pointing to the working store) fails fast before serving.
289
+ """
290
+ import argparse
291
+
292
+ parser = argparse.ArgumentParser(description="MintMory History MCP Server (read-only)")
293
+ parser.add_argument(
294
+ "--transport",
295
+ choices=["stdio", "sse"],
296
+ default="stdio",
297
+ help="Transport to use (default: stdio)",
298
+ )
299
+ parser.add_argument("--port", type=int, default=8082, help="Port for SSE transport")
300
+ parser.add_argument(
301
+ "--db",
302
+ default=None,
303
+ help="Path to history SQLite DB (sets MINTMORY_HISTORY_DB)",
304
+ )
305
+ args = parser.parse_args()
306
+
307
+ if args.db:
308
+ os.environ["MINTMORY_HISTORY_DB"] = args.db
309
+
310
+ # Guard: fail fast if the path resolves to the working store
311
+ _assert_not_working_db(_db_path())
312
+
313
+ if args.transport == "stdio":
314
+ mcp.run(transport="stdio")
315
+ else:
316
+ mcp.run(transport="sse", port=args.port)
317
+
318
+
319
+ if __name__ == "__main__":
320
+ main()
File without changes