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.
- mintmory_mcp-0.1.0/.gitignore +59 -0
- mintmory_mcp-0.1.0/LICENSE +21 -0
- mintmory_mcp-0.1.0/PKG-INFO +34 -0
- mintmory_mcp-0.1.0/README.md +8 -0
- mintmory_mcp-0.1.0/pyproject.toml +46 -0
- mintmory_mcp-0.1.0/src/mintmory/mcp/__init__.py +1 -0
- mintmory_mcp-0.1.0/src/mintmory/mcp/_schema.py +101 -0
- mintmory_mcp-0.1.0/src/mintmory/mcp/concise.py +69 -0
- mintmory_mcp-0.1.0/src/mintmory/mcp/history_server.py +320 -0
- mintmory_mcp-0.1.0/src/mintmory/mcp/py.typed +0 -0
- mintmory_mcp-0.1.0/src/mintmory/mcp/server.py +870 -0
- mintmory_mcp-0.1.0/tests/test_cochange_tools.py +451 -0
- mintmory_mcp-0.1.0/tests/test_concise.py +296 -0
- mintmory_mcp-0.1.0/tests/test_history_mcp.py +492 -0
- mintmory_mcp-0.1.0/tests/test_resources_prompts.py +432 -0
- mintmory_mcp-0.1.0/tests/test_telemetry_init.py +50 -0
- mintmory_mcp-0.1.0/tests/test_tools.py +1172 -0
|
@@ -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
|