agentmemdb 0.1.0__py3-none-any.whl

agentmemdb/__init__.py

@@ -0,0 +1,5 @@
+"""agentmemdb: local-first, shared long-term memory for AI agents, served over MCP."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

agentmemdb/__main__.py

@@ -0,0 +1,3 @@
+from agentmemdb.cli import main
+
+main()

agentmemdb/cli.py

@@ -0,0 +1,54 @@
+"""Command-line entry point: run the server over stdio or HTTP, or print the resolved setup."""
+
+import argparse
+import json
+import os
+from collections.abc import Sequence
+
+from agentmemdb import __version__
+from agentmemdb.config import ConfigError, load_settings
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentmemdb", description="Local-first, shared long-term memory for AI agents (MCP server)"
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http"],
+        default="stdio",
+        help="stdio (default, one process per client) or streamable HTTP on 127.0.0.1",
+    )
+    parser.add_argument("--port", type=int, default=8765, help="HTTP port (default: 8765); endpoint is /mcp")
+    parser.add_argument("--check", action="store_true", help="print the resolved database and config paths, then exit")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        settings = load_settings()
+    except ConfigError as err:
+        parser.exit(2, f"agentmemdb: error: {err}\n")
+
+    if args.check:
+        info = {
+            "version": __version__,
+            "db_path": settings.db_path,
+            "db_exists": os.path.exists(settings.db_path),
+            "config_path": settings.config_path,
+            "config_found": settings.config_found,
+            "auto_tags": len(settings.auto_tags),
+        }
+        print(json.dumps(info, indent=2))
+        return
+
+    from agentmemdb.server import mcp
+
+    if args.transport == "http":
+        mcp.settings.port = args.port
+        mcp.run(transport="streamable-http")
+    else:
+        mcp.run(transport="stdio")

agentmemdb/config.py

@@ -0,0 +1,92 @@
+"""Settings resolved from environment variables and the optional JSON config file."""
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+APP_NAME = "agentmemdb"
+
+BASE_INSTRUCTIONS = (
+    "Long-term memory that persists across sessions and is shared by every agent connected to it. "
+    "Search it (search_memory, find_by_entity, get_thread) when past context could help, and save decisions, "
+    "findings and facts worth keeping with save_memory; prefer append_memory over saving a near-duplicate. "
+    "search_memory returns snippets; use get_memory (or full_content=true) for the full text. "
+    'Pass save_memory entities as a JSON array of objects, e.g. [{"type":"service","value":"billing-api"}].'
+)
+
+
+class ConfigError(ValueError):
+    """The config file exists but cannot be used."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    db_path: str
+    config_path: str
+    config_found: bool = False
+    auto_tags: dict[str, re.Pattern[str]] = field(default_factory=dict)
+    instructions: str = BASE_INSTRUCTIONS
+
+    def tags_for(self, *texts: str) -> list[str]:
+        """Auto-tags whose pattern matches the given texts (lowercased)."""
+        text = " ".join(texts).lower()
+        return [tag for tag, pattern in self.auto_tags.items() if pattern.search(text)]
+
+
+def config_path() -> str:
+    """AGENTMEMDB_CONFIG, else $XDG_CONFIG_HOME/agentmemdb/config.json."""
+    return os.path.expanduser(
+        os.environ.get("AGENTMEMDB_CONFIG")
+        or os.path.join(os.environ.get("XDG_CONFIG_HOME") or "~/.config", APP_NAME, "config.json")
+    )
+
+
+def default_db_path() -> str:
+    """$XDG_DATA_HOME/agentmemdb/memory.db (default ~/.local/share/agentmemdb/memory.db)."""
+    return os.path.join(os.path.expanduser(os.environ.get("XDG_DATA_HOME") or "~/.local/share"), APP_NAME, "memory.db")
+
+
+def load_settings() -> Settings:
+    """Resolve settings; the database path is AGENTMEMDB_DB_PATH, then config db_path, then the default."""
+    path = config_path()
+    found = os.path.exists(path)
+    config = _read_config(path) if found else {}
+    db_path = os.environ.get("AGENTMEMDB_DB_PATH") or config.get("db_path") or default_db_path()
+    extra = config.get("instructions", "")
+    return Settings(
+        db_path=os.path.expanduser(db_path),
+        config_path=path,
+        config_found=found,
+        auto_tags=_compile_auto_tags(path, config.get("auto_tags", {})),
+        instructions="\n".join(filter(None, [BASE_INSTRUCTIONS, extra])),
+    )
+
+
+def _read_config(path: str) -> dict[str, Any]:
+    try:
+        with open(path, encoding="utf-8") as f:
+            config = json.load(f)
+    except (OSError, json.JSONDecodeError) as err:
+        raise ConfigError(f"cannot read config file {path}: {err}") from err
+    if not isinstance(config, dict):
+        raise ConfigError(f"config file {path} must contain a JSON object")
+    for key in ("db_path", "instructions"):
+        if not isinstance(config.get(key, ""), str):
+            raise ConfigError(f"config file {path}: {key!r} must be a string")
+    return config
+
+
+def _compile_auto_tags(path: str, auto_tags: Any) -> dict[str, re.Pattern[str]]:
+    if not isinstance(auto_tags, dict):
+        raise ConfigError(f'config file {path}: "auto_tags" must be an object of {{"tag": "regex"}}')
+    compiled = {}
+    for tag, pattern in auto_tags.items():
+        if not isinstance(pattern, str):
+            raise ConfigError(f"config file {path}: auto_tags[{tag!r}] must be a regex string")
+        try:
+            compiled[tag] = re.compile(pattern)
+        except re.error as err:
+            raise ConfigError(f"config file {path}: auto_tags[{tag!r}] is not a valid regex: {err}") from err
+    return compiled

agentmemdb/icon.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="agentmemdb">
+  <defs>
+    <linearGradient id="amdb-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4F46E5"/>
+      <stop offset="1" stop-color="#9333EA"/>
+    </linearGradient>
+    <linearGradient id="amdb-disc" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#FFFFFF"/>
+      <stop offset="1" stop-color="#E0E7FF"/>
+    </linearGradient>
+    <clipPath id="amdb-back"><rect width="256" height="128"/></clipPath>
+    <clipPath id="amdb-front"><rect y="128" width="256" height="128"/></clipPath>
+  </defs>
+  <rect width="256" height="256" rx="60" fill="url(#amdb-bg)"/>
+  <g transform="rotate(-18 128 128)" fill="none" stroke="#FBBF24" stroke-width="7">
+    <ellipse cx="128" cy="128" rx="104" ry="32" clip-path="url(#amdb-back)"/>
+  </g>
+  <g fill="url(#amdb-disc)">
+    <ellipse cx="128" cy="72" rx="56" ry="19" fill="#FFFFFF"/>
+    <path d="M72 82A56 19 0 0 0 184 82V111A56 19 0 0 1 72 111Z"/>
+    <path d="M72 121A56 19 0 0 0 184 121V150A56 19 0 0 1 72 150Z"/>
+    <path d="M72 160A56 19 0 0 0 184 160V189A56 19 0 0 1 72 189Z"/>
+  </g>
+  <g transform="rotate(-18 128 128)" fill="#FBBF24">
+    <ellipse cx="128" cy="128" rx="104" ry="32" fill="none" stroke="#FBBF24" stroke-width="7" clip-path="url(#amdb-front)"/>
+    <circle cx="24" cy="128" r="13"/>
+    <circle cx="232" cy="128" r="13"/>
+    <circle cx="150" cy="159" r="13"/>
+  </g>
+</svg>

agentmemdb/models.py

@@ -0,0 +1,93 @@
+"""Memory categories, importance levels and validation of tool inputs."""
+
+import json
+from datetime import datetime, timezone
+
+CATEGORIES = (
+    "conversation",  # summary of a conversation or session
+    "decision",  # a decision and why it was made
+    "incident",  # alert or incident investigation and resolution
+    "research",  # analysis, findings, deep dives
+    "person",  # a colleague or contact
+    "project",  # project context, status, goals
+    "howto",  # procedures and runbooks
+    "config",  # configuration and environment setup
+    "other",
+)
+
+IMPORTANCE_LEVELS = ("low", "normal", "high", "critical")
+IMPORTANCE_RANK = {level: rank for rank, level in enumerate(IMPORTANCE_LEVELS)}
+
+ENTITIES_HINT = 'Expected a JSON array of objects like [{"type":"service","value":"billing-api"}]'
+
+
+class ToolError(Exception):
+    """Invalid input or missing memory; returned to the agent as {"error": message}."""
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def parse_timestamp(value: str) -> datetime:
+    """Parse YYYY-MM-DD or ISO 8601; naive values are treated as UTC."""
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def is_expired(expires_at: str | None) -> bool:
+    if not expires_at:
+        return False
+    try:
+        return utc_now() > parse_timestamp(expires_at)
+    except (ValueError, TypeError, AttributeError):
+        return False
+
+
+def check_category(category: str) -> None:
+    if category not in CATEGORIES:
+        raise ToolError(f"Invalid category. Must be one of: {list(CATEGORIES)}")
+
+
+def check_importance(importance: str) -> None:
+    if importance not in IMPORTANCE_LEVELS:
+        raise ToolError(f"Invalid importance. Must be one of: {list(IMPORTANCE_LEVELS)}")
+
+
+def check_expiry(expires_at: str) -> None:
+    try:
+        parse_timestamp(expires_at)
+    except ValueError:
+        raise ToolError("Invalid expires_at. Use YYYY-MM-DD or an ISO 8601 timestamp") from None
+
+
+def parse_tags(tags: str) -> list[str]:
+    return [t.strip() for t in tags.split(",") if t.strip()]
+
+
+def parse_entities(entities: str) -> list[tuple[str, str]]:
+    """Parse the entities JSON into unique, lowercased (type, value) pairs."""
+    if not entities:
+        return []
+    try:
+        parsed = json.loads(entities)
+    except json.JSONDecodeError as err:
+        raise ToolError(f"Invalid entities JSON: {err}") from None
+    if not isinstance(parsed, list):
+        raise ToolError(f"Invalid entities: {ENTITIES_HINT}")
+    pairs = []
+    for entity in parsed:
+        if not (
+            isinstance(entity, dict)
+            and isinstance(entity.get("type"), str)
+            and isinstance(entity.get("value"), str)
+            and entity["type"].strip()
+            and entity["value"].strip()
+        ):
+            raise ToolError(f"Invalid entity {json.dumps(entity)}: {ENTITIES_HINT}")
+        pairs.append((entity["type"].strip().lower(), entity["value"].strip().lower()))
+    return list(dict.fromkeys(pairs))
+
+
+def clamp(limit: int, upper: int = 100) -> int:
+    return max(1, min(int(limit), upper))

agentmemdb/search.py

@@ -0,0 +1,156 @@
+"""Relevance search (FTS5 + BM25 with a substring fallback) and duplicate detection."""
+
+import re
+import sqlite3
+from typing import Any
+
+from agentmemdb.models import IMPORTANCE_LEVELS, IMPORTANCE_RANK
+
+Row = dict[str, Any]
+
+STOP_WORDS = {"the", "and", "for", "with", "from", "that", "this", "are", "was", "has", "have", "not", "but"}
+
+SEARCH_COLUMNS = (
+    "m.id, m.topic, m.category, m.tags, m.importance, m.thread_id, m.expires_at, "
+    "m.created_at, m.updated_at, LENGTH(m.content) AS content_length"
+)
+
+# BM25 weights for (topic, content, tags)
+BM25_WEIGHTS = (10.0, 1.0, 5.0)
+
+
+def filters(category: str = "", importance: str = "", include_expired: bool = False) -> tuple[str, list[Any]]:
+    """SQL conditions on alias m for category, minimum importance and expiry."""
+    sql, params = "", []
+    if category:
+        sql += " AND m.category = ?"
+        params.append(category)
+    if importance in IMPORTANCE_RANK:
+        allowed = IMPORTANCE_LEVELS[IMPORTANCE_RANK[importance] :]
+        sql += f" AND m.importance IN ({','.join('?' * len(allowed))})"
+        params += allowed
+    if not include_expired:
+        sql += " AND NOT is_expired(m.expires_at)"
+    return sql, params
+
+
+def search(db: sqlite3.Connection, query: str, filter_sql: str, filter_params: list[Any], limit: int) -> list[Row]:
+    """Try the query as typed, then all terms, then any term; fall back to substring matching."""
+    for fts_query in fts_queries(query):
+        results = _search_fts(db, fts_query, filter_sql, filter_params, limit)
+        if results:
+            return results
+    return _search_substring(db, query, filter_sql, filter_params)[:limit]
+
+
+def fts_phrase(term: str) -> str:
+    return '"' + term.replace('"', '""') + '"'
+
+
+def fts_queries(query: str) -> list[str]:
+    """FTS5 queries in order: as typed, every term (AND), any term (OR)."""
+    phrases = [fts_phrase(t) for t in query.split() if re.search(r"\w", t)]
+    queries = [query]
+    if phrases:
+        queries += [" ".join(phrases), " OR ".join(phrases)]
+    return list(dict.fromkeys(queries))
+
+
+def _search_fts(
+    db: sqlite3.Connection, fts_query: str, filter_sql: str, filter_params: list[Any], limit: int
+) -> list[Row]:
+    try:
+        rows = db.execute(
+            f"""SELECT {SEARCH_COLUMNS}, snippet(memories_fts, 1, '', '', '…', 32) AS snippet
+                FROM memories_fts f
+                JOIN memories m ON m.id = f.rowid
+                WHERE memories_fts MATCH ?{filter_sql}
+                ORDER BY bm25(memories_fts, {", ".join(map(str, BM25_WEIGHTS))}) LIMIT ?""",
+            [fts_query, *filter_params, limit],
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+    return [dict(r) for r in rows]
+
+
+def _search_substring(db: sqlite3.Connection, query: str, filter_sql: str, filter_params: list[Any]) -> list[Row]:
+    """Partial words FTS can't match (e.g. "gres" in "postgres"), ranked by words matched."""
+    words = [w.lower() for w in re.findall(r"\w+", query) if len(w) >= 2][:5]
+    if not words:
+        return []
+
+    where = " OR ".join("(m.topic LIKE ? OR m.content LIKE ? OR m.tags LIKE ?)" for _ in words)
+    rows = db.execute(
+        f"SELECT {SEARCH_COLUMNS}, m.content FROM memories m WHERE ({where}){filter_sql}",
+        [f"%{w}%" for w in words for _ in range(3)] + filter_params,
+    ).fetchall()
+
+    scored = []
+    for row in rows:
+        result = dict(row)
+        content = result.pop("content")
+        text = f"{result['topic']} {content} {result['tags']}".lower()
+        result["snippet"] = content[:200] + ("…" if len(content) > 200 else "")
+        scored.append((sum(w in text for w in words), result["updated_at"], result))
+    scored.sort(key=lambda s: (s[0], s[1]), reverse=True)
+    return [result for _, _, result in scored]
+
+
+def topic_words(text: str) -> set[str]:
+    """Significant words of a topic, ignoring stop words and short numbers like years."""
+    return {
+        w
+        for w in re.findall(r"\w+", text.lower())
+        if len(w) >= 3 and w not in STOP_WORDS and not (w.isdigit() and len(w) <= 4)
+    }
+
+
+def is_similar(words: set[str], other: set[str]) -> bool:
+    """At least two shared words, covering 60% of the shorter topic."""
+    shared = len(words & other)
+    return shared >= 2 and shared / min(len(words), len(other)) >= 0.6
+
+
+def find_similar(db: sqlite3.Connection, topic: str, limit: int = 3) -> list[Row]:
+    """Memories whose topic matches exactly or shares most of its significant words."""
+    duplicates = [
+        dict(r, exact_match=True)
+        for r in db.execute(
+            "SELECT id, topic, category, importance, created_at FROM memories WHERE LOWER(topic) = LOWER(?)",
+            (topic,),
+        )
+    ]
+    words = topic_words(topic)
+    if words:
+        rows = db.execute(
+            """SELECT m.id, m.topic, m.category, m.importance, m.created_at
+               FROM memories_fts f
+               JOIN memories m ON m.id = f.rowid
+               WHERE memories_fts MATCH ?
+               ORDER BY bm25(memories_fts) LIMIT 25""",
+            ("topic : (" + " OR ".join(fts_phrase(w) for w in words) + ")",),
+        ).fetchall()
+        seen = {d["id"] for d in duplicates}
+        duplicates += [dict(r) for r in rows if r["id"] not in seen and is_similar(words, topic_words(r["topic"]))]
+    return duplicates[:limit]
+
+
+def group_similar(memories: list[Row], limit: int) -> list[Row]:
+    """Group memories (oldest first) whose topics share most of their significant words."""
+    indexed = [(m, topic_words(m["topic"])) for m in memories]
+    groups: list[Row] = []
+    seen: set[int] = set()
+    for i, (memory, words) in enumerate(indexed):
+        if memory["id"] in seen or not words:
+            continue
+        similar = [
+            other
+            for other, other_words in indexed[i + 1 :]
+            if other["id"] not in seen and other_words and is_similar(words, other_words)
+        ]
+        if similar:
+            seen.update([memory["id"], *(o["id"] for o in similar)])
+            groups.append({"memory": memory, "similar_to": similar})
+            if len(groups) >= limit:
+                break
+    return groups