brainmemory-mcp 0.1.0__tar.gz

brainmemory_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 R&D ICWR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brainmemory_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: brainmemory-mcp
+Version: 0.1.0
+Summary: BrainMemory-MCP — a Model Context Protocol server exposing Cognitive memory tools over HTTP + SSE.
+Author: BrainMemory-MCP maintainers
+Maintainer: BrainMemory-MCP maintainers
+License: MIT
+Project-URL: Homepage, https://github.com/venturo/BrainMemory-MCP
+Project-URL: Repository, https://github.com/venturo/BrainMemory-MCP
+Project-URL: Issues, https://github.com/venturo/BrainMemory-MCP/issues
+Project-URL: Changelog, https://github.com/venturo/BrainMemory-MCP/tree/main/docs/changelog
+Keywords: mcp,model-context-protocol,memory,sse,cognitive,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: starlette>=0.37.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.2.0; extra == "build"
+Requires-Dist: twine>=5.0.0; extra == "build"
+Dynamic: license-file
+
+# BrainMemory-MCP
+
+A **Model Context Protocol (MCP)** server that gives AI/LLM agents a durable
+**brain memory** — the ability to store, recall, search, summarize, and forget
+information across sessions through standardized MCP tool calls.
+
+The server speaks MCP over **HTTP + Server-Sent Events (SSE)**, so remote
+MCP-capable clients (Claude, IDE agents, etc.) can connect over the network.
+Memory is persisted locally under **`~/.brainmemory-mcp`** (a SQLite database).
+
+## Cognitive Tools
+
+| Tool | Description |
+|------|-------------|
+| `store_memory` | Persist a new memory (content, category, tags, importance). |
+| `recall_memory` | Fetch a single memory by its id. |
+| `search_memory` | Find memories by free text, category, tags and/or importance. |
+| `list_memories` | List stored memories (most important & recent first). |
+| `update_memory` | Modify an existing memory (only supplied fields change). |
+| `forget_memory` | Delete a memory by id. |
+| `summarize_memories` | Summary statistics: totals, categories, top tags. |
+
+A read-only resource `brainmemory://stats` exposes the same summary as JSON.
+
+## Install
+
+From PyPI (once published):
+
+```bash
+python3 -m pip install brainmemory-mcp
+```
+
+From a local checkout:
+
+```bash
+python3 -m pip install .
+```
+
+Both install the package and a console script named `brainmemory-mcp`.
+
+For development (editable install):
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+To build/publish a release, see [`docs/RELEASING.md`](docs/RELEASING.md).
+
+## Run
+
+```bash
+# Defaults: 127.0.0.1:8765, memory in ~/.brainmemory-mcp
+brainmemory-mcp
+
+# Custom host/port and memory location
+brainmemory-mcp --host 0.0.0.0 --port 9000 --data-dir /path/to/memory
+
+# Or without the console script
+python3 -m brainmemory_mcp
+```
+
+Endpoints once running:
+
+- SSE stream:      `http://<host>:<port>/sse`
+- Message POST:    `http://<host>:<port>/messages/`
+
+### Configuration
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `--host` | `BRAINMEMORY_HOST` | `127.0.0.1` |
+| `--port` | `BRAINMEMORY_PORT` | `8765` |
+| `--data-dir` | `BRAINMEMORY_HOME` | `~/.brainmemory-mcp` |
+
+## Connect a client
+
+Point any MCP client that supports SSE at the `/sse` endpoint. Example client
+configuration (URL-based transport):
+
+```json
+{
+  "mcpServers": {
+    "brainmemory": {
+      "url": "http://127.0.0.1:8765/sse"
+    }
+  }
+}
+```
+
+## How memory is stored
+
+Memories live in `~/.brainmemory-mcp/memory.db` (SQLite, WAL mode). Each memory
+has: `id`, `content`, `category`, `tags`, `importance` (1–5), `created_at`,
+`updated_at`. Nothing is ever silently deleted — removal only happens through
+`forget_memory`.
+
+## License
+
+MIT

brainmemory_mcp-0.1.0/README.md

@@ -0,0 +1,99 @@
+# BrainMemory-MCP
+
+A **Model Context Protocol (MCP)** server that gives AI/LLM agents a durable
+**brain memory** — the ability to store, recall, search, summarize, and forget
+information across sessions through standardized MCP tool calls.
+
+The server speaks MCP over **HTTP + Server-Sent Events (SSE)**, so remote
+MCP-capable clients (Claude, IDE agents, etc.) can connect over the network.
+Memory is persisted locally under **`~/.brainmemory-mcp`** (a SQLite database).
+
+## Cognitive Tools
+
+| Tool | Description |
+|------|-------------|
+| `store_memory` | Persist a new memory (content, category, tags, importance). |
+| `recall_memory` | Fetch a single memory by its id. |
+| `search_memory` | Find memories by free text, category, tags and/or importance. |
+| `list_memories` | List stored memories (most important & recent first). |
+| `update_memory` | Modify an existing memory (only supplied fields change). |
+| `forget_memory` | Delete a memory by id. |
+| `summarize_memories` | Summary statistics: totals, categories, top tags. |
+
+A read-only resource `brainmemory://stats` exposes the same summary as JSON.
+
+## Install
+
+From PyPI (once published):
+
+```bash
+python3 -m pip install brainmemory-mcp
+```
+
+From a local checkout:
+
+```bash
+python3 -m pip install .
+```
+
+Both install the package and a console script named `brainmemory-mcp`.
+
+For development (editable install):
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+To build/publish a release, see [`docs/RELEASING.md`](docs/RELEASING.md).
+
+## Run
+
+```bash
+# Defaults: 127.0.0.1:8765, memory in ~/.brainmemory-mcp
+brainmemory-mcp
+
+# Custom host/port and memory location
+brainmemory-mcp --host 0.0.0.0 --port 9000 --data-dir /path/to/memory
+
+# Or without the console script
+python3 -m brainmemory_mcp
+```
+
+Endpoints once running:
+
+- SSE stream:      `http://<host>:<port>/sse`
+- Message POST:    `http://<host>:<port>/messages/`
+
+### Configuration
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `--host` | `BRAINMEMORY_HOST` | `127.0.0.1` |
+| `--port` | `BRAINMEMORY_PORT` | `8765` |
+| `--data-dir` | `BRAINMEMORY_HOME` | `~/.brainmemory-mcp` |
+
+## Connect a client
+
+Point any MCP client that supports SSE at the `/sse` endpoint. Example client
+configuration (URL-based transport):
+
+```json
+{
+  "mcpServers": {
+    "brainmemory": {
+      "url": "http://127.0.0.1:8765/sse"
+    }
+  }
+}
+```
+
+## How memory is stored
+
+Memories live in `~/.brainmemory-mcp/memory.db` (SQLite, WAL mode). Each memory
+has: `id`, `content`, `category`, `tags`, `importance` (1–5), `created_at`,
+`updated_at`. Nothing is ever silently deleted — removal only happens through
+`forget_memory`.
+
+## License
+
+MIT

brainmemory_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brainmemory-mcp"
+dynamic = ["version"]
+description = "BrainMemory-MCP — a Model Context Protocol server exposing Cognitive memory tools over HTTP + SSE."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "BrainMemory-MCP maintainers" }]
+maintainers = [{ name = "BrainMemory-MCP maintainers" }]
+keywords = ["mcp", "model-context-protocol", "memory", "sse", "cognitive", "llm", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "starlette>=0.37.0",
+    "uvicorn>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = ["ruff>=0.5.0", "black>=24.0.0"]
+build = ["build>=1.2.0", "twine>=5.0.0"]
+
+[project.scripts]
+brainmemory-mcp = "brainmemory_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/venturo/BrainMemory-MCP"
+Repository = "https://github.com/venturo/BrainMemory-MCP"
+Issues = "https://github.com/venturo/BrainMemory-MCP/issues"
+Changelog = "https://github.com/venturo/BrainMemory-MCP/tree/main/docs/changelog"
+
+[tool.setuptools.dynamic]
+version = { attr = "brainmemory_mcp.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]

brainmemory_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brainmemory_mcp-0.1.0/src/brainmemory_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""BrainMemory-MCP — Cognitive memory tools served over HTTP + SSE.
+
+A Model Context Protocol (MCP) server that gives AI/LLM agents a durable
+"brain memory": the ability to store, recall, search, update, summarize, and
+forget information across sessions through standardized MCP tool calls.
+
+Memory is persisted locally under ``~/.brainmemory-mcp``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .memory import MemoryStore, Memory, default_data_dir
+
+__all__ = ["MemoryStore", "Memory", "default_data_dir", "__version__"]

brainmemory_mcp-0.1.0/src/brainmemory_mcp/__main__.py

@@ -0,0 +1,63 @@
+"""Command-line entry point for BrainMemory-MCP.
+
+Usage:
+    brainmemory-mcp --host 0.0.0.0 --port 8765
+    python3 -m brainmemory_mcp
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+from . import __version__
+from .memory import DATA_DIR_ENV, default_data_dir
+from .server import run
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="brainmemory-mcp",
+        description=(
+            "BrainMemory-MCP — Cognitive memory tools for AI agents, served over "
+            "the Model Context Protocol using HTTP + SSE."
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("BRAINMEMORY_HOST", "127.0.0.1"),
+        help="Host/interface to bind (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("BRAINMEMORY_PORT", "8765")),
+        help="TCP port to listen on (default: 8765).",
+    )
+    parser.add_argument(
+        "--data-dir",
+        default=None,
+        help=(
+            "Directory to store memories in. "
+            f"Overrides ${DATA_DIR_ENV}. Default: {default_data_dir()}"
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        run(host=args.host, port=args.port, data_dir=args.data_dir)
+    except KeyboardInterrupt:  # pragma: no cover - interactive shutdown
+        print("\nBrainMemory-MCP stopped.", flush=True)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

brainmemory_mcp-0.1.0/src/brainmemory_mcp/memory.py

@@ -0,0 +1,318 @@
+"""Persistence layer for BrainMemory-MCP.
+
+Memories are stored in a local SQLite database under ``~/.brainmemory-mcp``.
+The store is intentionally small, deterministic, and dependency-free (stdlib
+``sqlite3`` only) so that the "brain memory" is safe and never silently loses
+data.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import uuid
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+# --------------------------------------------------------------------------- #
+# Paths
+# --------------------------------------------------------------------------- #
+
+DATA_DIR_ENV = "BRAINMEMORY_HOME"
+
+
+def default_data_dir() -> Path:
+    """Return the directory where memories are persisted.
+
+    Defaults to ``~/.brainmemory-mcp`` but can be overridden with the
+    ``BRAINMEMORY_HOME`` environment variable.
+    """
+    override = os.environ.get(DATA_DIR_ENV)
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path.home() / ".brainmemory-mcp"
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# --------------------------------------------------------------------------- #
+# Model
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class Memory:
+    """A single stored memory."""
+
+    id: str
+    content: str
+    category: str
+    tags: list[str]
+    importance: int
+    created_at: str
+    updated_at: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _row_to_memory(row: sqlite3.Row) -> Memory:
+    return Memory(
+        id=row["id"],
+        content=row["content"],
+        category=row["category"],
+        tags=json.loads(row["tags"]) if row["tags"] else [],
+        importance=row["importance"],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Store
+# --------------------------------------------------------------------------- #
+
+
+class MemoryStore:
+    """SQLite-backed memory store.
+
+    Thread/async note: each public method opens a short-lived connection, so the
+    store is safe to use from the MCP server's request handlers.
+    """
+
+    def __init__(self, data_dir: Path | None = None) -> None:
+        self.data_dir = Path(data_dir) if data_dir else default_data_dir()
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path = self.data_dir / "memory.db"
+        self._init_db()
+
+    # -- internal ----------------------------------------------------------- #
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL;")
+        conn.execute("PRAGMA foreign_keys=ON;")
+        return conn
+
+    def _init_db(self) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS memories (
+                    id          TEXT PRIMARY KEY,
+                    content     TEXT NOT NULL,
+                    category    TEXT NOT NULL DEFAULT 'general',
+                    tags        TEXT NOT NULL DEFAULT '[]',
+                    importance  INTEGER NOT NULL DEFAULT 3,
+                    created_at  TEXT NOT NULL,
+                    updated_at  TEXT NOT NULL
+                );
+                """
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance);"
+            )
+            conn.commit()
+
+    # -- public API --------------------------------------------------------- #
+
+    def store(
+        self,
+        content: str,
+        *,
+        category: str = "general",
+        tags: Iterable[str] | None = None,
+        importance: int = 3,
+    ) -> Memory:
+        """Persist a new memory and return it."""
+        if not content or not content.strip():
+            raise ValueError("content must not be empty")
+        importance = max(1, min(5, int(importance)))
+        now = _utcnow()
+        mem = Memory(
+            id=uuid.uuid4().hex,
+            content=content.strip(),
+            category=(category or "general").strip() or "general",
+            tags=sorted({t.strip() for t in (tags or []) if t and t.strip()}),
+            importance=importance,
+            created_at=now,
+            updated_at=now,
+        )
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO memories
+                    (id, content, category, tags, importance, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    mem.id,
+                    mem.content,
+                    mem.category,
+                    json.dumps(mem.tags),
+                    mem.importance,
+                    mem.created_at,
+                    mem.updated_at,
+                ),
+            )
+            conn.commit()
+        return mem
+
+    def get(self, memory_id: str) -> Memory | None:
+        """Return a single memory by id, or ``None`` if it does not exist."""
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM memories WHERE id = ?", (memory_id,)
+            ).fetchone()
+        return _row_to_memory(row) if row else None
+
+    def search(
+        self,
+        query: str | None = None,
+        *,
+        category: str | None = None,
+        tags: Iterable[str] | None = None,
+        min_importance: int | None = None,
+        limit: int = 20,
+    ) -> list[Memory]:
+        """Search memories by free text, category, tags and/or importance."""
+        clauses: list[str] = []
+        params: list[Any] = []
+
+        if query and query.strip():
+            clauses.append("(content LIKE ? OR tags LIKE ? OR category LIKE ?)")
+            like = f"%{query.strip()}%"
+            params.extend([like, like, like])
+
+        if category and category.strip():
+            clauses.append("category = ?")
+            params.append(category.strip())
+
+        if min_importance is not None:
+            clauses.append("importance >= ?")
+            params.append(max(1, min(5, int(min_importance))))
+
+        wanted_tags = [t.strip() for t in (tags or []) if t and t.strip()]
+        for tag in wanted_tags:
+            clauses.append("tags LIKE ?")
+            params.append(f'%"{tag}"%')
+
+        where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+        sql = (
+            f"SELECT * FROM memories {where} "
+            "ORDER BY importance DESC, updated_at DESC LIMIT ?"
+        )
+        params.append(max(1, int(limit)))
+
+        with self._connect() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [_row_to_memory(r) for r in rows]
+
+    def list_all(self, *, limit: int = 100, offset: int = 0) -> list[Memory]:
+        """Return memories ordered by importance then recency."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM memories "
+                "ORDER BY importance DESC, updated_at DESC "
+                "LIMIT ? OFFSET ?",
+                (max(1, int(limit)), max(0, int(offset))),
+            ).fetchall()
+        return [_row_to_memory(r) for r in rows]
+
+    def update(
+        self,
+        memory_id: str,
+        *,
+        content: str | None = None,
+        category: str | None = None,
+        tags: Iterable[str] | None = None,
+        importance: int | None = None,
+    ) -> Memory | None:
+        """Update fields of an existing memory. Returns the updated memory."""
+        current = self.get(memory_id)
+        if current is None:
+            return None
+
+        if content is not None and content.strip():
+            current.content = content.strip()
+        if category is not None and category.strip():
+            current.category = category.strip()
+        if tags is not None:
+            current.tags = sorted({t.strip() for t in tags if t and t.strip()})
+        if importance is not None:
+            current.importance = max(1, min(5, int(importance)))
+        current.updated_at = _utcnow()
+
+        with self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE memories
+                   SET content = ?, category = ?, tags = ?, importance = ?, updated_at = ?
+                 WHERE id = ?
+                """,
+                (
+                    current.content,
+                    current.category,
+                    json.dumps(current.tags),
+                    current.importance,
+                    current.updated_at,
+                    current.id,
+                ),
+            )
+            conn.commit()
+        return current
+
+    def forget(self, memory_id: str) -> bool:
+        """Delete a memory by id. Returns True if a row was removed."""
+        with self._connect() as conn:
+            cur = conn.execute("DELETE FROM memories WHERE id = ?", (memory_id,))
+            conn.commit()
+            return cur.rowcount > 0
+
+    def clear(self) -> int:
+        """Delete ALL memories. Returns the number of rows removed."""
+        with self._connect() as conn:
+            cur = conn.execute("DELETE FROM memories")
+            conn.commit()
+            return cur.rowcount
+
+    def stats(self) -> dict[str, Any]:
+        """Return summary statistics about the stored memories."""
+        with self._connect() as conn:
+            total = conn.execute("SELECT COUNT(*) AS c FROM memories").fetchone()["c"]
+            by_category = {
+                row["category"]: row["c"]
+                for row in conn.execute(
+                    "SELECT category, COUNT(*) AS c FROM memories "
+                    "GROUP BY category ORDER BY c DESC"
+                ).fetchall()
+            }
+            avg_importance_row = conn.execute(
+                "SELECT AVG(importance) AS a FROM memories"
+            ).fetchone()
+            avg_importance = round(avg_importance_row["a"], 2) if avg_importance_row["a"] else 0
+
+            all_tags: dict[str, int] = {}
+            for row in conn.execute("SELECT tags FROM memories").fetchall():
+                for tag in json.loads(row["tags"]) if row["tags"] else []:
+                    all_tags[tag] = all_tags.get(tag, 0) + 1
+
+        return {
+            "total": total,
+            "by_category": by_category,
+            "top_tags": dict(
+                sorted(all_tags.items(), key=lambda kv: kv[1], reverse=True)[:10]
+            ),
+            "average_importance": avg_importance,
+            "data_dir": str(self.data_dir),
+            "db_path": str(self.db_path),
+        }

brainmemory_mcp-0.1.0/src/brainmemory_mcp/server.py

@@ -0,0 +1,214 @@
+"""BrainMemory-MCP server.
+
+Exposes Cognitive memory tools over the Model Context Protocol using the
+HTTP + Server-Sent Events (SSE) transport. Built on the official ``mcp`` SDK
+(``FastMCP``).
+
+Cognitive tools:
+    - store_memory        : persist a new memory
+    - recall_memory       : fetch a single memory by id
+    - search_memory       : find memories by text / category / tags / importance
+    - list_memories       : list stored memories (most important first)
+    - update_memory       : modify an existing memory
+    - forget_memory       : delete a memory
+    - summarize_memories  : summary statistics over stored memories
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .memory import MemoryStore, default_data_dir
+
+# --------------------------------------------------------------------------- #
+# Factory
+# --------------------------------------------------------------------------- #
+
+
+def create_server(
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    data_dir: str | None = None,
+) -> FastMCP:
+    """Create and configure the BrainMemory-MCP :class:`FastMCP` server."""
+
+    store = MemoryStore(data_dir=data_dir) if data_dir else MemoryStore()
+
+    mcp = FastMCP(
+        name="BrainMemory-MCP",
+        instructions=(
+            "Cognitive brain-memory for AI agents. Use these tools to persist "
+            "durable memories across sessions, then recall/search them later. "
+            "Store concise, self-contained facts; tag them and set an "
+            "importance from 1 (trivial) to 5 (critical). Search before "
+            "storing to avoid duplicates."
+        ),
+        host=host,
+        port=port,
+    )
+
+    # ----------------------------------------------------------------- tools #
+
+    @mcp.tool()
+    def store_memory(
+        content: str,
+        category: str = "general",
+        tags: list[str] | None = None,
+        importance: int = 3,
+    ) -> dict[str, Any]:
+        """Persist a new memory in the brain.
+
+        Args:
+            content: The information to remember (a concise, self-contained fact).
+            category: A grouping label, e.g. "preferences", "facts", "tasks".
+            tags: Optional keywords to make the memory easier to find later.
+            importance: 1 (trivial) .. 5 (critical). Defaults to 3.
+
+        Returns:
+            The stored memory including its generated ``id``.
+        """
+        mem = store.store(
+            content,
+            category=category,
+            tags=tags or [],
+            importance=importance,
+        )
+        return {"status": "stored", "memory": mem.to_dict()}
+
+    @mcp.tool()
+    def recall_memory(memory_id: str) -> dict[str, Any]:
+        """Recall a single memory by its id.
+
+        Args:
+            memory_id: The id returned when the memory was stored.
+        """
+        mem = store.get(memory_id)
+        if mem is None:
+            return {"status": "not_found", "memory_id": memory_id}
+        return {"status": "ok", "memory": mem.to_dict()}
+
+    @mcp.tool()
+    def search_memory(
+        query: str = "",
+        category: str | None = None,
+        tags: list[str] | None = None,
+        min_importance: int | None = None,
+        limit: int = 20,
+    ) -> dict[str, Any]:
+        """Search memories by free text, category, tags and/or importance.
+
+        Args:
+            query: Free-text matched against content, tags and category.
+            category: Restrict to a single category.
+            tags: Only memories containing ALL of these tags.
+            min_importance: Only memories with importance >= this value (1..5).
+            limit: Maximum number of results (default 20).
+
+        Returns:
+            A list of matching memories, most important & most recent first.
+        """
+        results = store.search(
+            query=query or None,
+            category=category,
+            tags=tags or None,
+            min_importance=min_importance,
+            limit=limit,
+        )
+        return {
+            "status": "ok",
+            "count": len(results),
+            "memories": [m.to_dict() for m in results],
+        }
+
+    @mcp.tool()
+    def list_memories(limit: int = 100, offset: int = 0) -> dict[str, Any]:
+        """List stored memories, most important and most recent first.
+
+        Args:
+            limit: Maximum number of memories to return (default 100).
+            offset: Number of memories to skip (for pagination).
+        """
+        results = store.list_all(limit=limit, offset=offset)
+        return {
+            "status": "ok",
+            "count": len(results),
+            "memories": [m.to_dict() for m in results],
+        }
+
+    @mcp.tool()
+    def update_memory(
+        memory_id: str,
+        content: str | None = None,
+        category: str | None = None,
+        tags: list[str] | None = None,
+        importance: int | None = None,
+    ) -> dict[str, Any]:
+        """Update fields of an existing memory (only provided fields change).
+
+        Args:
+            memory_id: The id of the memory to update.
+            content: New content (optional).
+            category: New category (optional).
+            tags: Replacement tag list (optional).
+            importance: New importance 1..5 (optional).
+        """
+        mem = store.update(
+            memory_id,
+            content=content,
+            category=category,
+            tags=tags,
+            importance=importance,
+        )
+        if mem is None:
+            return {"status": "not_found", "memory_id": memory_id}
+        return {"status": "updated", "memory": mem.to_dict()}
+
+    @mcp.tool()
+    def forget_memory(memory_id: str) -> dict[str, Any]:
+        """Forget (delete) a memory by its id.
+
+        Args:
+            memory_id: The id of the memory to delete.
+        """
+        removed = store.forget(memory_id)
+        return {
+            "status": "forgotten" if removed else "not_found",
+            "memory_id": memory_id,
+        }
+
+    @mcp.tool()
+    def summarize_memories() -> dict[str, Any]:
+        """Summarize the brain memory: totals, categories, top tags, etc."""
+        return {"status": "ok", "summary": store.stats()}
+
+    # ------------------------------------------------------------- resources #
+
+    @mcp.resource("brainmemory://stats")
+    def stats_resource() -> str:
+        """Live summary statistics of the stored memories (JSON)."""
+        import json
+
+        return json.dumps(store.stats(), indent=2)
+
+    return mcp
+
+
+def run(
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    data_dir: str | None = None,
+) -> None:
+    """Create the server and run it over the SSE transport."""
+    server = create_server(host=host, port=port, data_dir=data_dir)
+    resolved_dir = data_dir or str(default_data_dir())
+    print(
+        f"BrainMemory-MCP (SSE) listening on http://{host}:{port}/sse\n"
+        f"  message endpoint : http://{host}:{port}/messages/\n"
+        f"  memory directory : {resolved_dir}",
+        flush=True,
+    )
+    server.run(transport="sse")

brainmemory_mcp-0.1.0/src/brainmemory_mcp.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: brainmemory-mcp
+Version: 0.1.0
+Summary: BrainMemory-MCP — a Model Context Protocol server exposing Cognitive memory tools over HTTP + SSE.
+Author: BrainMemory-MCP maintainers
+Maintainer: BrainMemory-MCP maintainers
+License: MIT
+Project-URL: Homepage, https://github.com/venturo/BrainMemory-MCP
+Project-URL: Repository, https://github.com/venturo/BrainMemory-MCP
+Project-URL: Issues, https://github.com/venturo/BrainMemory-MCP/issues
+Project-URL: Changelog, https://github.com/venturo/BrainMemory-MCP/tree/main/docs/changelog
+Keywords: mcp,model-context-protocol,memory,sse,cognitive,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: starlette>=0.37.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.2.0; extra == "build"
+Requires-Dist: twine>=5.0.0; extra == "build"
+Dynamic: license-file
+
+# BrainMemory-MCP
+
+A **Model Context Protocol (MCP)** server that gives AI/LLM agents a durable
+**brain memory** — the ability to store, recall, search, summarize, and forget
+information across sessions through standardized MCP tool calls.
+
+The server speaks MCP over **HTTP + Server-Sent Events (SSE)**, so remote
+MCP-capable clients (Claude, IDE agents, etc.) can connect over the network.
+Memory is persisted locally under **`~/.brainmemory-mcp`** (a SQLite database).
+
+## Cognitive Tools
+
+| Tool | Description |
+|------|-------------|
+| `store_memory` | Persist a new memory (content, category, tags, importance). |
+| `recall_memory` | Fetch a single memory by its id. |
+| `search_memory` | Find memories by free text, category, tags and/or importance. |
+| `list_memories` | List stored memories (most important & recent first). |
+| `update_memory` | Modify an existing memory (only supplied fields change). |
+| `forget_memory` | Delete a memory by id. |
+| `summarize_memories` | Summary statistics: totals, categories, top tags. |
+
+A read-only resource `brainmemory://stats` exposes the same summary as JSON.
+
+## Install
+
+From PyPI (once published):
+
+```bash
+python3 -m pip install brainmemory-mcp
+```
+
+From a local checkout:
+
+```bash
+python3 -m pip install .
+```
+
+Both install the package and a console script named `brainmemory-mcp`.
+
+For development (editable install):
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+To build/publish a release, see [`docs/RELEASING.md`](docs/RELEASING.md).
+
+## Run
+
+```bash
+# Defaults: 127.0.0.1:8765, memory in ~/.brainmemory-mcp
+brainmemory-mcp
+
+# Custom host/port and memory location
+brainmemory-mcp --host 0.0.0.0 --port 9000 --data-dir /path/to/memory
+
+# Or without the console script
+python3 -m brainmemory_mcp
+```
+
+Endpoints once running:
+
+- SSE stream:      `http://<host>:<port>/sse`
+- Message POST:    `http://<host>:<port>/messages/`
+
+### Configuration
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `--host` | `BRAINMEMORY_HOST` | `127.0.0.1` |
+| `--port` | `BRAINMEMORY_PORT` | `8765` |
+| `--data-dir` | `BRAINMEMORY_HOME` | `~/.brainmemory-mcp` |
+
+## Connect a client
+
+Point any MCP client that supports SSE at the `/sse` endpoint. Example client
+configuration (URL-based transport):
+
+```json
+{
+  "mcpServers": {
+    "brainmemory": {
+      "url": "http://127.0.0.1:8765/sse"
+    }
+  }
+}
+```
+
+## How memory is stored
+
+Memories live in `~/.brainmemory-mcp/memory.db` (SQLite, WAL mode). Each memory
+has: `id`, `content`, `category`, `tags`, `importance` (1–5), `created_at`,
+`updated_at`. Nothing is ever silently deleted — removal only happens through
+`forget_memory`.
+
+## License
+
+MIT

brainmemory_mcp-0.1.0/src/brainmemory_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/brainmemory_mcp/__init__.py
+src/brainmemory_mcp/__main__.py
+src/brainmemory_mcp/memory.py
+src/brainmemory_mcp/server.py
+src/brainmemory_mcp.egg-info/PKG-INFO
+src/brainmemory_mcp.egg-info/SOURCES.txt
+src/brainmemory_mcp.egg-info/dependency_links.txt
+src/brainmemory_mcp.egg-info/entry_points.txt
+src/brainmemory_mcp.egg-info/requires.txt
+src/brainmemory_mcp.egg-info/top_level.txt

brainmemory_mcp-0.1.0/src/brainmemory_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

brainmemory_mcp-0.1.0/src/brainmemory_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+brainmemory-mcp = brainmemory_mcp.__main__:main

brainmemory_mcp-0.1.0/src/brainmemory_mcp.egg-info/requires.txt

@@ -0,0 +1,11 @@
+mcp>=1.2.0
+starlette>=0.37.0
+uvicorn>=0.30.0
+
+[build]
+build>=1.2.0
+twine>=5.0.0
+
+[dev]
+ruff>=0.5.0
+black>=24.0.0

brainmemory_mcp-0.1.0/src/brainmemory_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+brainmemory_mcp