Upload 17 files

config.json

@@ -0,0 +1,31 @@
+{
+    "name": "memory-mcp",
+    "description": "Three-tier memory system MCP server (session / episodic / semantic-RAG)",
+    "version": "0.1.0",
+
+    "data_root": "data",
+    "embedding_model": "all-MiniLM-L6-v2",
+    "session_ttl_seconds": 3600,
+
+    "transport": "stdio",
+    "sse_port": 8765,
+
+    "memory_tiers": {
+        "session": {
+            "description": "Short-term conversation context",
+            "storage": "data/session",
+            "max_entries_per_session": 50,
+            "ttl_seconds": 3600
+        },
+        "episodic": {
+            "description": "Mid-term task & event history",
+            "storage": "data/events"
+        },
+        "semantic": {
+            "description": "Long-term vector RAG knowledge base",
+            "vector_storage": "data/vector",
+            "md_storage": "data/vector/docs",
+            "collection_name": "memory_semantic"
+        }
+    }
+}

data/events/.gitkeep

@@ -0,0 +1 @@
+# Placeholder — episodic event files stored here as *.md

data/session/.gitkeep

@@ -0,0 +1,2 @@
+# Placeholder — session data stored here
+# Each session gets a subfolder: session/<session_id>/*.md

data/vector/.gitkeep

@@ -0,0 +1,2 @@
+# Placeholder — semantic vector data & markdown docs stored here
+# Subfolders: chroma_db/  and  docs/

data/vector/docs/.gitkeep

@@ -0,0 +1 @@
+# Placeholder — markdown mirrors of vector entries

memory/__init__.py

@@ -0,0 +1,22 @@
+"""
+Memory System MCP Server
+========================
+Three-tier memory architecture for AI agents:
+- Short-Term (Session): Conversation context, ephemeral
+- Episodic (Events): Past tasks and interactions, mid-term
+- Semantic (Vector): RAG-backed long-term knowledge base
+"""
+
+from memory.models import MemoryEntry, MemoryTier, SearchResult
+from memory.session import SessionMemory
+from memory.events import EpisodicMemory
+from memory.vector import SemanticMemory
+
+__all__ = [
+    "MemoryEntry",
+    "MemoryTier",
+    "SearchResult",
+    "SessionMemory",
+    "EpisodicMemory",
+    "SemanticMemory",
+]

memory/events.py

@@ -0,0 +1,154 @@
+"""
+Episodic Memory – Past Tasks & Events
+=======================================
+Stores discrete events / task completions as Markdown files
+under  memory/events/*.md
+
+Each event has a timestamp, outcome, and optional linked entities.
+Supports keyword search and time-range queries.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .models import MemoryEntry, MemoryTier
+
+
+class EpisodicMemory:
+    """File-backed store for task / event memories."""
+
+    def __init__(self, base_dir: str = "memory/events"):
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        # id → MemoryEntry (in-memory index)
+        self._index: Dict[str, MemoryEntry] = {}
+        self._load_from_disk()
+
+    # ── CRUD ─────────────────────────────────────────────────
+
+    def create(
+        self,
+        content: str,
+        title: str = "",
+        tags: Optional[List[str]] = None,
+        importance: float = 0.5,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: str = "",
+    ) -> MemoryEntry:
+        entry = MemoryEntry(
+            content=content,
+            title=title or self._auto_title(content),
+            tier=MemoryTier.EPISODIC,
+            tags=tags or [],
+            importance=importance,
+            metadata=metadata or {},
+            source=source,
+            created_at=datetime.utcnow().isoformat(),
+            updated_at=datetime.utcnow().isoformat(),
+        )
+        self._index[entry.id] = entry
+        self._persist(entry)
+        return entry
+
+    def read(self, entry_id: str) -> Optional[MemoryEntry]:
+        entry = self._index.get(entry_id)
+        if entry:
+            entry.access_count += 1
+            entry.updated_at = datetime.utcnow().isoformat()
+            self._persist(entry)
+        return entry
+
+    def update(self, entry_id: str, **kwargs) -> Optional[MemoryEntry]:
+        entry = self._index.get(entry_id)
+        if not entry:
+            return None
+        for k, v in kwargs.items():
+            if hasattr(entry, k) and k not in ("id", "tier", "created_at"):
+                setattr(entry, k, v)
+        entry.updated_at = datetime.utcnow().isoformat()
+        self._persist(entry)
+        return entry
+
+    def delete(self, entry_id: str) -> bool:
+        if entry_id not in self._index:
+            return False
+        del self._index[entry_id]
+        path = self._entry_path(entry_id)
+        if path.exists():
+            path.unlink()
+        return True
+
+    def list_entries(
+        self,
+        tag: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        limit: int = 50,
+    ) -> List[MemoryEntry]:
+        """List events, optionally filtered by tag and/or time range."""
+        entries = list(self._index.values())
+
+        if tag:
+            entries = [e for e in entries if tag in e.tags]
+        if since:
+            entries = [e for e in entries if e.created_at >= since]
+        if until:
+            entries = [e for e in entries if e.created_at <= until]
+
+        # newest first
+        entries.sort(key=lambda e: e.created_at, reverse=True)
+        return entries[:limit]
+
+    def search(self, query: str, limit: int = 10) -> List[MemoryEntry]:
+        """Keyword search across episodic memories."""
+        q = query.lower()
+        scored: List[tuple] = []
+        for entry in self._index.values():
+            text = f"{entry.title} {entry.content} {' '.join(entry.tags)}".lower()
+            if q in text:
+                # rudimentary relevance: importance + recency
+                scored.append((entry, entry.importance))
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [e for e, _ in scored[:limit]]
+
+    def count(self) -> int:
+        return len(self._index)
+
+    # ── timeline helpers ─────────────────────────────────────
+
+    def recent(self, n: int = 10) -> List[MemoryEntry]:
+        """Get the N most recent events."""
+        entries = sorted(self._index.values(), key=lambda e: e.created_at, reverse=True)
+        return entries[:n]
+
+    def by_tag(self, tag: str) -> List[MemoryEntry]:
+        return [e for e in self._index.values() if tag in e.tags]
+
+    # ── persistence ──────────────────────────────────────────
+
+    def _entry_path(self, entry_id: str) -> Path:
+        return self.base_dir / f"{entry_id}.md"
+
+    def _persist(self, entry: MemoryEntry):
+        path = self._entry_path(entry.id)
+        path.write_text(entry.to_markdown(), encoding="utf-8")
+
+    def _load_from_disk(self):
+        for md_file in self.base_dir.glob("*.md"):
+            try:
+                text = md_file.read_text(encoding="utf-8")
+                entry = MemoryEntry.from_markdown(text)
+                entry.tier = MemoryTier.EPISODIC
+                self._index[entry.id] = entry
+            except Exception:
+                pass
+
+    @staticmethod
+    def _auto_title(content: str) -> str:
+        """Generate a short title from content."""
+        first_line = content.strip().split("\n")[0][:80]
+        return first_line if first_line else "Untitled Event"

memory/models.py

@@ -0,0 +1,117 @@
+"""Data models for the Memory System."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class MemoryTier(str, Enum):
+    """Which memory layer an entry belongs to."""
+    SESSION = "session"      # short-term / conversation context
+    EPISODIC = "episodic"    # mid-term / past tasks & events
+    SEMANTIC = "semantic"    # long-term / vector-backed knowledge
+
+
+@dataclass
+class MemoryEntry:
+    """A single memory record stored across tiers."""
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    content: str = ""
+    title: str = ""
+    tier: MemoryTier = MemoryTier.SESSION
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    importance: float = 0.5          # 0.0 – 1.0
+    access_count: int = 0
+    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())
+    session_id: Optional[str] = None  # groups session memories
+    source: str = ""                  # origin of the memory
+
+    # ── helpers ──────────────────────────────────────────────
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["tier"] = self.tier.value
+        return d
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MemoryEntry":
+        data = dict(data)  # shallow copy
+        if "tier" in data and isinstance(data["tier"], str):
+            data["tier"] = MemoryTier(data["tier"])
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+    def to_markdown(self) -> str:
+        """Render as a Markdown document with YAML front-matter."""
+        lines = [
+            "---",
+            f"id: {self.id}",
+            f"title: \"{self.title}\"",
+            f"tier: {self.tier.value}",
+            f"tags: [{', '.join(self.tags)}]",
+            f"importance: {self.importance}",
+            f"access_count: {self.access_count}",
+            f"created_at: {self.created_at}",
+            f"updated_at: {self.updated_at}",
+        ]
+        if self.session_id:
+            lines.append(f"session_id: {self.session_id}")
+        if self.source:
+            lines.append(f"source: \"{self.source}\"")
+        if self.metadata:
+            import json
+            lines.append(f"metadata: {json.dumps(self.metadata)}")
+        lines.append("---")
+        lines.append("")
+        lines.append(self.content)
+        return "\n".join(lines)
+
+    @classmethod
+    def from_markdown(cls, text: str) -> "MemoryEntry":
+        """Parse a Markdown document with YAML front-matter."""
+        import re, json as _json
+
+        fm_match = re.match(r"^---\n(.*?)\n---\n?(.*)", text, re.DOTALL)
+        if not fm_match:
+            return cls(content=text)
+
+        front, body = fm_match.group(1), fm_match.group(2).strip()
+        data: Dict[str, Any] = {"content": body}
+
+        for line in front.splitlines():
+            line = line.strip()
+            if not line or ":" not in line:
+                continue
+            key, _, val = line.partition(":")
+            key = key.strip()
+            val = val.strip().strip('"')
+
+            if key == "tags":
+                # parse [tag1, tag2]
+                inner = val.strip("[]")
+                data["tags"] = [t.strip() for t in inner.split(",") if t.strip()]
+            elif key == "importance":
+                data["importance"] = float(val)
+            elif key == "access_count":
+                data["access_count"] = int(val)
+            elif key == "metadata":
+                try:
+                    data["metadata"] = _json.loads(val)
+                except _json.JSONDecodeError:
+                    data["metadata"] = {}
+            else:
+                data[key] = val
+
+        return cls.from_dict(data)
+
+
+@dataclass
+class SearchResult:
+    """Wrapper returned by semantic search."""
+    entry: MemoryEntry
+    score: float = 0.0       # similarity / relevance
+    distance: float = 0.0    # raw distance from vector DB

memory/session.py

@@ -0,0 +1,172 @@
+"""
+Short-Term / Session Memory
+============================
+Stores conversation context and ephemeral data as Markdown files
+under  memory/session/<session_id>/*.md
+
+Entries expire after a configurable TTL (default 1 hour).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections import OrderedDict
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .models import MemoryEntry, MemoryTier
+
+
+class SessionMemory:
+    """In-memory + file-backed short-term memory store."""
+
+    DEFAULT_TTL = 3600          # seconds – 1 hour
+    MAX_ENTRIES_PER_SESSION = 50
+
+    def __init__(self, base_dir: str = "memory/session", ttl: int = DEFAULT_TTL):
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.ttl = ttl
+        # session_id → OrderedDict[entry_id, MemoryEntry]
+        self._cache: Dict[str, OrderedDict[str, MemoryEntry]] = {}
+        self._load_from_disk()
+
+    # ── CRUD ─────────────────────────────────────────────────
+
+    def create(self, entry: MemoryEntry, session_id: str = "default") -> MemoryEntry:
+        """Add a new entry to a session."""
+        entry.tier = MemoryTier.SESSION
+        entry.session_id = session_id
+        entry.created_at = datetime.utcnow().isoformat()
+        entry.updated_at = entry.created_at
+
+        bucket = self._cache.setdefault(session_id, OrderedDict())
+        # evict oldest when full
+        while len(bucket) >= self.MAX_ENTRIES_PER_SESSION:
+            bucket.popitem(last=False)
+        bucket[entry.id] = entry
+        self._persist(entry, session_id)
+        return entry
+
+    def read(self, entry_id: str, session_id: str = "default") -> Optional[MemoryEntry]:
+        """Retrieve a single entry by ID."""
+        bucket = self._cache.get(session_id, {})
+        entry = bucket.get(entry_id)
+        if entry:
+            entry.access_count += 1
+            entry.updated_at = datetime.utcnow().isoformat()
+            self._persist(entry, session_id)
+        return entry
+
+    def update(self, entry_id: str, session_id: str = "default", **kwargs) -> Optional[MemoryEntry]:
+        """Update fields on an existing entry."""
+        bucket = self._cache.get(session_id, {})
+        entry = bucket.get(entry_id)
+        if not entry:
+            return None
+        for k, v in kwargs.items():
+            if hasattr(entry, k) and k not in ("id", "tier", "created_at"):
+                setattr(entry, k, v)
+        entry.updated_at = datetime.utcnow().isoformat()
+        self._persist(entry, session_id)
+        return entry
+
+    def delete(self, entry_id: str, session_id: str = "default") -> bool:
+        """Remove an entry."""
+        bucket = self._cache.get(session_id, {})
+        if entry_id not in bucket:
+            return False
+        del bucket[entry_id]
+        path = self._entry_path(entry_id, session_id)
+        if path.exists():
+            path.unlink()
+        return True
+
+    def list_entries(self, session_id: str = "default", tag: Optional[str] = None) -> List[MemoryEntry]:
+        """List all entries in a session, optionally filtered by tag."""
+        bucket = self._cache.get(session_id, OrderedDict())
+        entries = list(bucket.values())
+        if tag:
+            entries = [e for e in entries if tag in e.tags]
+        return entries
+
+    def list_sessions(self) -> List[str]:
+        """List all known session IDs."""
+        return list(self._cache.keys())
+
+    def clear_session(self, session_id: str = "default") -> int:
+        """Drop all entries in a session. Returns count deleted."""
+        bucket = self._cache.pop(session_id, OrderedDict())
+        count = len(bucket)
+        session_dir = self.base_dir / session_id
+        if session_dir.exists():
+            for f in session_dir.glob("*.md"):
+                f.unlink()
+            try:
+                session_dir.rmdir()
+            except OSError:
+                pass
+        return count
+
+    def gc(self) -> int:
+        """Garbage-collect expired entries across all sessions. Returns count removed."""
+        now = time.time()
+        removed = 0
+        for sid in list(self._cache.keys()):
+            for eid in list(self._cache[sid].keys()):
+                entry = self._cache[sid][eid]
+                created_ts = datetime.fromisoformat(entry.created_at).timestamp()
+                if now - created_ts > self.ttl:
+                    self.delete(eid, sid)
+                    removed += 1
+        return removed
+
+    # ── search helpers ───────────────────────────────────────
+
+    def search(self, query: str, session_id: Optional[str] = None, limit: int = 10) -> List[MemoryEntry]:
+        """Simple keyword search across session memories."""
+        query_lower = query.lower()
+        results: List[MemoryEntry] = []
+
+        sessions = [session_id] if session_id else list(self._cache.keys())
+        for sid in sessions:
+            for entry in self._cache.get(sid, {}).values():
+                text = f"{entry.title} {entry.content} {' '.join(entry.tags)}".lower()
+                if query_lower in text:
+                    results.append(entry)
+                    if len(results) >= limit:
+                        return results
+        return results
+
+    # ── persistence ──────────────────────────────────────────
+
+    def _entry_path(self, entry_id: str, session_id: str) -> Path:
+        d = self.base_dir / session_id
+        d.mkdir(parents=True, exist_ok=True)
+        return d / f"{entry_id}.md"
+
+    def _persist(self, entry: MemoryEntry, session_id: str):
+        path = self._entry_path(entry.id, session_id)
+        path.write_text(entry.to_markdown(), encoding="utf-8")
+
+    def _load_from_disk(self):
+        """Bootstrap cache from existing .md files."""
+        if not self.base_dir.exists():
+            return
+        for session_dir in self.base_dir.iterdir():
+            if not session_dir.is_dir():
+                continue
+            sid = session_dir.name
+            bucket = self._cache.setdefault(sid, OrderedDict())
+            for md_file in sorted(session_dir.glob("*.md")):
+                try:
+                    text = md_file.read_text(encoding="utf-8")
+                    entry = MemoryEntry.from_markdown(text)
+                    entry.session_id = sid
+                    entry.tier = MemoryTier.SESSION
+                    bucket[entry.id] = entry
+                except Exception:
+                    pass  # skip corrupt files

memory/vector.py

@@ -0,0 +1,343 @@
+"""
+Semantic / Vector Memory – RAG Layer
+=====================================
+Long-term knowledge stored in ChromaDB with sentence-transformer embeddings.
+Also persists each entry as a Markdown file under  memory/vector/*.md
+for human-readability and version control.
+
+This is the RAG backbone:
+  • Add documents → embed + store
+  • Query by natural language → cosine similarity search
+  • Full CRUD with automatic re-embedding on update
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .models import MemoryEntry, MemoryTier, SearchResult
+
+logger = logging.getLogger(__name__)
+
+# ── optional heavy deps (graceful fallback) ──────────────────
+try:
+    import chromadb
+    from chromadb.config import Settings as ChromaSettings
+    CHROMA_AVAILABLE = True
+except ImportError:
+    CHROMA_AVAILABLE = False
+
+try:
+    from sentence_transformers import SentenceTransformer
+    ST_AVAILABLE = True
+except ImportError:
+    ST_AVAILABLE = False
+
+
+class _SentenceTransformerEmbedder:
+    """Wraps sentence-transformers for ChromaDB's EmbeddingFunction protocol."""
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        if not ST_AVAILABLE:
+            raise ImportError("sentence-transformers is required for semantic memory")
+        self.model = SentenceTransformer(model_name)
+        self.model_name = model_name
+
+    def __call__(self, input: List[str]) -> List[List[float]]:
+        embeddings = self.model.encode(input, show_progress_bar=False)
+        return embeddings.tolist()
+
+
+class SemanticMemory:
+    """ChromaDB-backed vector store with Markdown file mirror."""
+
+    COLLECTION_NAME = "memory_semantic"
+    DEFAULT_MODEL = "all-MiniLM-L6-v2"
+
+    def __init__(
+        self,
+        vector_dir: str = "memory/vector",
+        md_dir: str = "memory/vector/docs",
+        model_name: str = DEFAULT_MODEL,
+        collection_name: str = COLLECTION_NAME,
+    ):
+        self.vector_dir = Path(vector_dir)
+        self.md_dir = Path(md_dir)
+        self.vector_dir.mkdir(parents=True, exist_ok=True)
+        self.md_dir.mkdir(parents=True, exist_ok=True)
+        self.model_name = model_name
+        self.collection_name = collection_name
+
+        # ChromaDB setup
+        if CHROMA_AVAILABLE:
+            self._client = chromadb.PersistentClient(
+                path=str(self.vector_dir / "chroma_db"),
+            )
+            # Embedding function
+            if ST_AVAILABLE:
+                self._embed_fn = _SentenceTransformerEmbedder(model_name)
+                self._collection = self._client.get_or_create_collection(
+                    name=collection_name,
+                    embedding_function=self._embed_fn,
+                    metadata={"hnsw:space": "cosine"},
+                )
+            else:
+                # fall back to Chroma's built-in default embedder
+                self._collection = self._client.get_or_create_collection(
+                    name=collection_name,
+                    metadata={"hnsw:space": "cosine"},
+                )
+                self._embed_fn = None
+            logger.info(
+                "SemanticMemory ready  –  ChromaDB @ %s  |  model=%s  |  docs=%d",
+                self.vector_dir, model_name, self._collection.count(),
+            )
+        else:
+            self._client = None
+            self._collection = None
+            self._embed_fn = None
+            logger.warning("chromadb not installed – semantic memory operates in file-only mode")
+
+    # ── CRUD ─────────────────────────────────────────────────
+
+    def create(
+        self,
+        content: str,
+        title: str = "",
+        tags: Optional[List[str]] = None,
+        importance: float = 0.5,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: str = "",
+    ) -> MemoryEntry:
+        """Add a new document to the vector store + Markdown mirror."""
+        entry = MemoryEntry(
+            content=content,
+            title=title or content[:80],
+            tier=MemoryTier.SEMANTIC,
+            tags=tags or [],
+            importance=importance,
+            metadata=metadata or {},
+            source=source,
+            created_at=datetime.utcnow().isoformat(),
+            updated_at=datetime.utcnow().isoformat(),
+        )
+        self._upsert_vector(entry)
+        self._persist_md(entry)
+        return entry
+
+    def read(self, entry_id: str) -> Optional[MemoryEntry]:
+        """Retrieve by ID."""
+        if self._collection is None:
+            return self._read_from_md(entry_id)
+        try:
+            result = self._collection.get(ids=[entry_id], include=["documents", "metadatas"])
+            if not result["ids"]:
+                return None
+            entry = self._result_to_entry(result, 0)
+            entry.access_count += 1
+            entry.updated_at = datetime.utcnow().isoformat()
+            self._upsert_vector(entry)
+            self._persist_md(entry)
+            return entry
+        except Exception as exc:
+            logger.error("read failed: %s", exc)
+            return self._read_from_md(entry_id)
+
+    def update(self, entry_id: str, **kwargs) -> Optional[MemoryEntry]:
+        """Update fields and re-embed if content changed."""
+        entry = self.read(entry_id)
+        if not entry:
+            return None
+        for k, v in kwargs.items():
+            if hasattr(entry, k) and k not in ("id", "tier", "created_at"):
+                setattr(entry, k, v)
+        entry.updated_at = datetime.utcnow().isoformat()
+        self._upsert_vector(entry)
+        self._persist_md(entry)
+        return entry
+
+    def delete(self, entry_id: str) -> bool:
+        """Remove from vector store and disk."""
+        if self._collection is not None:
+            try:
+                self._collection.delete(ids=[entry_id])
+            except Exception:
+                pass
+        md_path = self.md_dir / f"{entry_id}.md"
+        if md_path.exists():
+            md_path.unlink()
+            return True
+        return False
+
+    # ── search / RAG ─────────────────────────────────────────
+
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        where: Optional[Dict[str, Any]] = None,
+    ) -> List[SearchResult]:
+        """Semantic similarity search. This is the RAG retrieval endpoint."""
+        if self._collection is None:
+            return self._keyword_fallback(query, limit)
+
+        kwargs: Dict[str, Any] = {
+            "query_texts": [query],
+            "n_results": min(limit, self._collection.count() or 1),
+            "include": ["documents", "metadatas", "distances"],
+        }
+        if where:
+            kwargs["where"] = where
+
+        try:
+            results = self._collection.query(**kwargs)
+        except Exception as exc:
+            logger.error("vector search failed: %s", exc)
+            return self._keyword_fallback(query, limit)
+
+        search_results: List[SearchResult] = []
+        if results and results["ids"] and results["ids"][0]:
+            for idx in range(len(results["ids"][0])):
+                entry = self._query_result_to_entry(results, idx)
+                dist = results["distances"][0][idx] if results.get("distances") else 0
+                score = max(0.0, 1.0 - dist)  # cosine distance → similarity
+                search_results.append(SearchResult(entry=entry, score=score, distance=dist))
+
+        return search_results
+
+    def list_entries(self, limit: int = 100, tag: Optional[str] = None) -> List[MemoryEntry]:
+        """List all stored entries (up to limit)."""
+        if self._collection is None:
+            return self._list_from_md(limit, tag)
+
+        result = self._collection.get(
+            include=["documents", "metadatas"],
+            limit=limit,
+        )
+        entries = []
+        for idx in range(len(result["ids"])):
+            entry = self._result_to_entry(result, idx)
+            if tag and tag not in entry.tags:
+                continue
+            entries.append(entry)
+        return entries
+
+    def count(self) -> int:
+        if self._collection is not None:
+            return self._collection.count()
+        return len(list(self.md_dir.glob("*.md")))
+
+    # ── internals ────────────────────────────────────────────
+
+    def _upsert_vector(self, entry: MemoryEntry):
+        if self._collection is None:
+            return
+        meta = {
+            "title": entry.title,
+            "tier": entry.tier.value,
+            "tags": json.dumps(entry.tags),
+            "importance": entry.importance,
+            "access_count": entry.access_count,
+            "created_at": entry.created_at,
+            "updated_at": entry.updated_at,
+            "source": entry.source,
+        }
+        self._collection.upsert(
+            ids=[entry.id],
+            documents=[entry.content],
+            metadatas=[meta],
+        )
+
+    def _persist_md(self, entry: MemoryEntry):
+        path = self.md_dir / f"{entry.id}.md"
+        path.write_text(entry.to_markdown(), encoding="utf-8")
+
+    def _read_from_md(self, entry_id: str) -> Optional[MemoryEntry]:
+        path = self.md_dir / f"{entry_id}.md"
+        if not path.exists():
+            return None
+        text = path.read_text(encoding="utf-8")
+        return MemoryEntry.from_markdown(text)
+
+    def _result_to_entry(self, result: dict, idx: int) -> MemoryEntry:
+        meta = result["metadatas"][idx] if result.get("metadatas") else {}
+        doc = result["documents"][idx] if result.get("documents") else ""
+        entry_id = result["ids"][idx]
+        tags = []
+        if "tags" in meta:
+            try:
+                tags = json.loads(meta["tags"])
+            except (json.JSONDecodeError, TypeError):
+                tags = []
+        return MemoryEntry(
+            id=entry_id,
+            content=doc,
+            title=meta.get("title", ""),
+            tier=MemoryTier.SEMANTIC,
+            tags=tags,
+            importance=float(meta.get("importance", 0.5)),
+            access_count=int(meta.get("access_count", 0)),
+            created_at=meta.get("created_at", ""),
+            updated_at=meta.get("updated_at", ""),
+            source=meta.get("source", ""),
+        )
+
+    def _query_result_to_entry(self, results: dict, idx: int) -> MemoryEntry:
+        meta = results["metadatas"][0][idx] if results.get("metadatas") else {}
+        doc = results["documents"][0][idx] if results.get("documents") else ""
+        entry_id = results["ids"][0][idx]
+        tags = []
+        if "tags" in meta:
+            try:
+                tags = json.loads(meta["tags"])
+            except (json.JSONDecodeError, TypeError):
+                tags = []
+        return MemoryEntry(
+            id=entry_id,
+            content=doc,
+            title=meta.get("title", ""),
+            tier=MemoryTier.SEMANTIC,
+            tags=tags,
+            importance=float(meta.get("importance", 0.5)),
+            access_count=int(meta.get("access_count", 0)),
+            created_at=meta.get("created_at", ""),
+            updated_at=meta.get("updated_at", ""),
+            source=meta.get("source", ""),
+        )
+
+    def _keyword_fallback(self, query: str, limit: int) -> List[SearchResult]:
+        """When ChromaDB is unavailable, fall back to keyword search over MD files."""
+        q = query.lower()
+        results: List[SearchResult] = []
+        for md_file in self.md_dir.glob("*.md"):
+            try:
+                text = md_file.read_text(encoding="utf-8")
+                if q in text.lower():
+                    entry = MemoryEntry.from_markdown(text)
+                    entry.tier = MemoryTier.SEMANTIC
+                    results.append(SearchResult(entry=entry, score=0.5))
+                    if len(results) >= limit:
+                        break
+            except Exception:
+                pass
+        return results
+
+    def _list_from_md(self, limit: int, tag: Optional[str]) -> List[MemoryEntry]:
+        entries: List[MemoryEntry] = []
+        for md_file in sorted(self.md_dir.glob("*.md"), reverse=True):
+            try:
+                text = md_file.read_text(encoding="utf-8")
+                entry = MemoryEntry.from_markdown(text)
+                entry.tier = MemoryTier.SEMANTIC
+                if tag and tag not in entry.tags:
+                    continue
+                entries.append(entry)
+                if len(entries) >= limit:
+                    break
+            except Exception:
+                pass
+        return entries

memory_server.py

@@ -0,0 +1,572 @@
+#!/usr/bin/env python3
+"""
+Memory System MCP Server
+=========================
+A three-tier memory architecture exposed as MCP tools for AI agents.
+
+Tiers
+-----
+1. **Session** (short-term)  – conversation context, auto-expiring
+2. **Episodic** (mid-term)   – past tasks & events, searchable timeline
+3. **Semantic** (long-term)  – vector-backed RAG knowledge base
+
+Every entry is also persisted as a human-readable Markdown file.
+
+Usage
+-----
+    python memory_server.py                # stdio transport (for MCP clients)
+    python memory_server.py --sse 8765     # SSE transport on port 8765
+
+Transport is auto-detected via MCP protocol when run from an MCP host.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+# ── local imports ────────────────────────────────────────────
+from memory.session import SessionMemory
+from memory.events import EpisodicMemory
+from memory.vector import SemanticMemory
+from memory.models import MemoryEntry, MemoryTier
+
+# ── logging ──────────────────────────────────────────────────
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
+)
+logger = logging.getLogger("memory-mcp")
+
+# ── resolve data root ───────────────────────────────────────
+DATA_ROOT = Path(os.environ.get("MEMORY_DATA_ROOT", Path(__file__).parent / "data"))
+DATA_ROOT.mkdir(parents=True, exist_ok=True)
+
+EMBEDDING_MODEL = os.environ.get("MEMORY_EMBEDDING_MODEL", "all-MiniLM-L6-v2")
+SESSION_TTL = int(os.environ.get("MEMORY_SESSION_TTL", "3600"))
+
+# ── initialise stores ───────────────────────────────────────
+session_store = SessionMemory(
+    base_dir=str(DATA_ROOT / "session"),
+    ttl=SESSION_TTL,
+)
+episodic_store = EpisodicMemory(
+    base_dir=str(DATA_ROOT / "events"),
+)
+semantic_store = SemanticMemory(
+    vector_dir=str(DATA_ROOT / "vector"),
+    md_dir=str(DATA_ROOT / "vector" / "docs"),
+    model_name=EMBEDDING_MODEL,
+)
+
+logger.info("🧠 Memory stores initialised  –  data_root=%s", DATA_ROOT)
+
+# ── MCP server ───────────────────────────────────────────────
+mcp = FastMCP("memory")
+
+
+# =====================================================================
+#  RESOURCES  – browse memory state
+# =====================================================================
+
+@mcp.resource("memory://status")
+def memory_status() -> str:
+    """Overview of the memory system."""
+    return json.dumps({
+        "session": {
+            "sessions": session_store.list_sessions(),
+            "total_entries": sum(
+                len(session_store.list_entries(sid))
+                for sid in session_store.list_sessions()
+            ),
+        },
+        "episodic": {
+            "total_entries": episodic_store.count(),
+        },
+        "semantic": {
+            "total_entries": semantic_store.count(),
+            "embedding_model": EMBEDDING_MODEL,
+        },
+    }, indent=2)
+
+
+@mcp.resource("memory://session/{session_id}")
+def session_resource(session_id: str) -> str:
+    """List entries in a session."""
+    entries = session_store.list_entries(session_id)
+    return json.dumps([e.to_dict() for e in entries], indent=2)
+
+
+@mcp.resource("memory://events/recent")
+def recent_events_resource() -> str:
+    """The 20 most recent episodic events."""
+    entries = episodic_store.recent(20)
+    return json.dumps([e.to_dict() for e in entries], indent=2)
+
+
+# =====================================================================
+#  PROMPTS
+# =====================================================================
+
+@mcp.prompt()
+def memory_context_prompt(query: str = "", session_id: str = "default") -> str:
+    """Build a comprehensive memory context for an LLM prompt."""
+    parts: List[str] = ["# Agent Memory Context\n"]
+
+    # session context
+    session_entries = session_store.list_entries(session_id)
+    if session_entries:
+        parts.append("## Recent Conversation (Session)")
+        for e in session_entries[-5:]:
+            parts.append(f"- [{e.created_at}] {e.title}: {e.content[:200]}")
+        parts.append("")
+
+    # episodic
+    recent = episodic_store.recent(5)
+    if recent:
+        parts.append("## Recent Tasks (Episodic)")
+        for e in recent:
+            parts.append(f"- [{e.created_at}] {e.title}: {e.content[:200]}")
+        parts.append("")
+
+    # semantic / RAG
+    if query:
+        hits = semantic_store.search(query, limit=3)
+        if hits:
+            parts.append("## Relevant Knowledge (Semantic / RAG)")
+            for h in hits:
+                parts.append(f"- [score={h.score:.2f}] {h.entry.title}: {h.entry.content[:300]}")
+            parts.append("")
+
+    return "\n".join(parts)
+
+
+# =====================================================================
+#  TOOLS  – full CRUD for each tier
+# =====================================================================
+
+# ─── Session (short-term) ───────────────────────────────────
+
+@mcp.tool()
+def session_create(
+    content: str,
+    title: str = "",
+    tags: str = "",
+    session_id: str = "default",
+    importance: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    Create a new short-term / session memory entry.
+
+    Stores conversation context that auto-expires after the configured TTL.
+    Persisted as a Markdown file under data/session/<session_id>/.
+    """
+    entry = MemoryEntry(
+        content=content,
+        title=title or content[:60],
+        tags=[t.strip() for t in tags.split(",") if t.strip()] if tags else [],
+        importance=importance,
+    )
+    result = session_store.create(entry, session_id=session_id)
+    return {"status": "created", "entry": result.to_dict()}
+
+
+@mcp.tool()
+def session_read(entry_id: str, session_id: str = "default") -> Dict[str, Any]:
+    """Read a single session memory entry by ID."""
+    entry = session_store.read(entry_id, session_id)
+    if not entry:
+        return {"status": "not_found", "entry_id": entry_id}
+    return {"status": "ok", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def session_update(
+    entry_id: str,
+    session_id: str = "default",
+    content: str = "",
+    title: str = "",
+    tags: str = "",
+    importance: float = -1,
+) -> Dict[str, Any]:
+    """Update a session memory entry. Only provided fields are changed."""
+    kwargs: Dict[str, Any] = {}
+    if content:
+        kwargs["content"] = content
+    if title:
+        kwargs["title"] = title
+    if tags:
+        kwargs["tags"] = [t.strip() for t in tags.split(",") if t.strip()]
+    if importance >= 0:
+        kwargs["importance"] = importance
+    entry = session_store.update(entry_id, session_id, **kwargs)
+    if not entry:
+        return {"status": "not_found", "entry_id": entry_id}
+    return {"status": "updated", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def session_delete(entry_id: str, session_id: str = "default") -> Dict[str, Any]:
+    """Delete a session memory entry."""
+    ok = session_store.delete(entry_id, session_id)
+    return {"status": "deleted" if ok else "not_found", "entry_id": entry_id}
+
+
+@mcp.tool()
+def session_list(session_id: str = "default", tag: str = "") -> Dict[str, Any]:
+    """List all entries in a session, optionally filtered by tag."""
+    entries = session_store.list_entries(session_id, tag=tag or None)
+    return {"count": len(entries), "entries": [e.to_dict() for e in entries]}
+
+
+@mcp.tool()
+def session_search(query: str, session_id: str = "", limit: int = 10) -> Dict[str, Any]:
+    """Keyword search across session memories."""
+    results = session_store.search(query, session_id=session_id or None, limit=limit)
+    return {"count": len(results), "entries": [e.to_dict() for e in results]}
+
+
+@mcp.tool()
+def session_clear(session_id: str = "default") -> Dict[str, Any]:
+    """Clear all entries from a session."""
+    count = session_store.clear_session(session_id)
+    return {"status": "cleared", "session_id": session_id, "deleted": count}
+
+
+@mcp.tool()
+def session_gc() -> Dict[str, Any]:
+    """Garbage-collect expired session entries across all sessions."""
+    removed = session_store.gc()
+    return {"status": "gc_complete", "removed": removed}
+
+
+# ─── Episodic (mid-term) ────────────────────────────────────
+
+@mcp.tool()
+def episodic_create(
+    content: str,
+    title: str = "",
+    tags: str = "",
+    importance: float = 0.5,
+    source: str = "",
+) -> Dict[str, Any]:
+    """
+    Record a new episodic memory (task completion, event, interaction).
+
+    Stored as a timestamped Markdown file under data/events/.
+    """
+    tag_list = [t.strip() for t in tags.split(",") if t.strip()] if tags else []
+    entry = episodic_store.create(
+        content=content,
+        title=title,
+        tags=tag_list,
+        importance=importance,
+        source=source,
+    )
+    return {"status": "created", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def episodic_read(entry_id: str) -> Dict[str, Any]:
+    """Read a single episodic memory by ID."""
+    entry = episodic_store.read(entry_id)
+    if not entry:
+        return {"status": "not_found", "entry_id": entry_id}
+    return {"status": "ok", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def episodic_update(
+    entry_id: str,
+    content: str = "",
+    title: str = "",
+    tags: str = "",
+    importance: float = -1,
+) -> Dict[str, Any]:
+    """Update an episodic memory entry."""
+    kwargs: Dict[str, Any] = {}
+    if content:
+        kwargs["content"] = content
+    if title:
+        kwargs["title"] = title
+    if tags:
+        kwargs["tags"] = [t.strip() for t in tags.split(",") if t.strip()]
+    if importance >= 0:
+        kwargs["importance"] = importance
+    entry = episodic_store.update(entry_id, **kwargs)
+    if not entry:
+        return {"status": "not_found", "entry_id": entry_id}
+    return {"status": "updated", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def episodic_delete(entry_id: str) -> Dict[str, Any]:
+    """Delete an episodic memory entry."""
+    ok = episodic_store.delete(entry_id)
+    return {"status": "deleted" if ok else "not_found", "entry_id": entry_id}
+
+
+@mcp.tool()
+def episodic_list(
+    tag: str = "",
+    since: str = "",
+    until: str = "",
+    limit: int = 50,
+) -> Dict[str, Any]:
+    """List episodic memories, optionally filtered by tag and/or time range (ISO format)."""
+    entries = episodic_store.list_entries(
+        tag=tag or None,
+        since=since or None,
+        until=until or None,
+        limit=limit,
+    )
+    return {"count": len(entries), "entries": [e.to_dict() for e in entries]}
+
+
+@mcp.tool()
+def episodic_search(query: str, limit: int = 10) -> Dict[str, Any]:
+    """Keyword search across episodic memories."""
+    results = episodic_store.search(query, limit=limit)
+    return {"count": len(results), "entries": [e.to_dict() for e in results]}
+
+
+@mcp.tool()
+def episodic_recent(n: int = 10) -> Dict[str, Any]:
+    """Get the N most recent episodic events."""
+    entries = episodic_store.recent(n)
+    return {"count": len(entries), "entries": [e.to_dict() for e in entries]}
+
+
+# ─── Semantic / RAG (long-term) ─────────────────────────────
+
+@mcp.tool()
+def semantic_create(
+    content: str,
+    title: str = "",
+    tags: str = "",
+    importance: float = 0.5,
+    source: str = "",
+) -> Dict[str, Any]:
+    """
+    Add a document to the semantic / RAG knowledge base.
+
+    The content is embedded via sentence-transformers and stored in ChromaDB
+    for similarity search. Also persisted as a Markdown file.
+    """
+    tag_list = [t.strip() for t in tags.split(",") if t.strip()] if tags else []
+    entry = semantic_store.create(
+        content=content,
+        title=title,
+        tags=tag_list,
+        importance=importance,
+        source=source,
+    )
+    return {"status": "created", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def semantic_read(entry_id: str) -> Dict[str, Any]:
+    """Read a single semantic memory by ID."""
+    entry = semantic_store.read(entry_id)
+    if not entry:
+        return {"status": "not_found", "entry_id": entry_id}
+    return {"status": "ok", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def semantic_update(
+    entry_id: str,
+    content: str = "",
+    title: str = "",
+    tags: str = "",
+    importance: float = -1,
+) -> Dict[str, Any]:
+    """Update a semantic memory entry. Re-embeds automatically if content changes."""
+    kwargs: Dict[str, Any] = {}
+    if content:
+        kwargs["content"] = content
+    if title:
+        kwargs["title"] = title
+    if tags:
+        kwargs["tags"] = [t.strip() for t in tags.split(",") if t.strip()]
+    if importance >= 0:
+        kwargs["importance"] = importance
+    entry = semantic_store.update(entry_id, **kwargs)
+    if not entry:
+        return {"status": "not_found", "entry_id": entry_id}
+    return {"status": "updated", "entry": entry.to_dict()}
+
+
+@mcp.tool()
+def semantic_delete(entry_id: str) -> Dict[str, Any]:
+    """Delete a semantic memory entry from vector store and disk."""
+    ok = semantic_store.delete(entry_id)
+    return {"status": "deleted" if ok else "not_found", "entry_id": entry_id}
+
+
+@mcp.tool()
+def semantic_search(query: str, limit: int = 5) -> Dict[str, Any]:
+    """
+    Semantic similarity search (RAG retrieval).
+
+    Finds the most relevant documents in the knowledge base using
+    vector cosine similarity. This is the primary RAG endpoint.
+    """
+    results = semantic_store.search(query, limit=limit)
+    return {
+        "count": len(results),
+        "results": [
+            {
+                "score": round(r.score, 4),
+                "distance": round(r.distance, 4),
+                "entry": r.entry.to_dict(),
+            }
+            for r in results
+        ],
+    }
+
+
+@mcp.tool()
+def semantic_list(limit: int = 100, tag: str = "") -> Dict[str, Any]:
+    """List all entries in the semantic knowledge base."""
+    entries = semantic_store.list_entries(limit=limit, tag=tag or None)
+    return {"count": len(entries), "entries": [e.to_dict() for e in entries]}
+
+
+# ─── Cross-tier utilities ───────────────────────────────────
+
+@mcp.tool()
+def memory_search_all(query: str, limit: int = 5) -> Dict[str, Any]:
+    """
+    Search across ALL memory tiers (session + episodic + semantic).
+
+    Combines keyword search from session & episodic with
+    semantic vector search. Returns unified results sorted by relevance.
+    """
+    results: Dict[str, Any] = {}
+
+    # session
+    s_hits = session_store.search(query, limit=limit)
+    results["session"] = [e.to_dict() for e in s_hits]
+
+    # episodic
+    e_hits = episodic_store.search(query, limit=limit)
+    results["episodic"] = [e.to_dict() for e in e_hits]
+
+    # semantic (RAG)
+    v_hits = semantic_store.search(query, limit=limit)
+    results["semantic"] = [
+        {"score": round(r.score, 4), "entry": r.entry.to_dict()}
+        for r in v_hits
+    ]
+
+    results["total"] = len(s_hits) + len(e_hits) + len(v_hits)
+    return results
+
+
+@mcp.tool()
+def memory_promote(entry_id: str, from_tier: str, to_tier: str) -> Dict[str, Any]:
+    """
+    Promote a memory entry from one tier to another.
+
+    E.g. promote a session memory to episodic, or episodic to semantic.
+    The entry is copied to the target tier (source is kept).
+    """
+    # read from source
+    source_entry: Optional[MemoryEntry] = None
+    if from_tier == "session":
+        source_entry = session_store.read(entry_id)
+    elif from_tier == "episodic":
+        source_entry = episodic_store.read(entry_id)
+    elif from_tier == "semantic":
+        source_entry = semantic_store.read(entry_id)
+
+    if not source_entry:
+        return {"status": "not_found", "entry_id": entry_id, "tier": from_tier}
+
+    # write to target
+    if to_tier == "session":
+        new_entry = MemoryEntry(
+            content=source_entry.content,
+            title=source_entry.title,
+            tags=source_entry.tags,
+            importance=source_entry.importance,
+            metadata=source_entry.metadata,
+            source=f"promoted from {from_tier}:{entry_id}",
+        )
+        result = session_store.create(new_entry)
+    elif to_tier == "episodic":
+        result = episodic_store.create(
+            content=source_entry.content,
+            title=source_entry.title,
+            tags=source_entry.tags,
+            importance=source_entry.importance,
+            metadata=source_entry.metadata,
+            source=f"promoted from {from_tier}:{entry_id}",
+        )
+    elif to_tier == "semantic":
+        result = semantic_store.create(
+            content=source_entry.content,
+            title=source_entry.title,
+            tags=source_entry.tags,
+            importance=source_entry.importance,
+            metadata=source_entry.metadata,
+            source=f"promoted from {from_tier}:{entry_id}",
+        )
+    else:
+        return {"status": "error", "message": f"Unknown target tier: {to_tier}"}
+
+    return {
+        "status": "promoted",
+        "from": from_tier,
+        "to": to_tier,
+        "original_id": entry_id,
+        "new_entry": result.to_dict(),
+    }
+
+
+@mcp.tool()
+def memory_stats() -> Dict[str, Any]:
+    """Get statistics about all memory tiers."""
+    sessions = session_store.list_sessions()
+    session_total = sum(len(session_store.list_entries(sid)) for sid in sessions)
+    return {
+        "session": {
+            "sessions": len(sessions),
+            "total_entries": session_total,
+            "ttl_seconds": SESSION_TTL,
+        },
+        "episodic": {
+            "total_entries": episodic_store.count(),
+        },
+        "semantic": {
+            "total_entries": semantic_store.count(),
+            "embedding_model": EMBEDDING_MODEL,
+        },
+        "data_root": str(DATA_ROOT),
+    }
+
+
+# =====================================================================
+#  ENTRY POINT
+# =====================================================================
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Memory System MCP Server")
+    parser.add_argument("--sse", type=int, default=0, help="Run SSE transport on this port")
+    args = parser.parse_args()
+
+    if args.sse:
+        logger.info("🚀 Starting Memory MCP server (SSE) on port %d", args.sse)
+        mcp.run(transport="sse", sse_params={"port": args.sse})
+    else:
+        logger.info("🚀 Starting Memory MCP server (stdio)")
+        mcp.run(transport="stdio")

requirements.txt

@@ -0,0 +1,13 @@
+# Memory System MCP Server – Dependencies
+
+# MCP SDK
+mcp[cli]>=1.0.0
+
+# Vector store
+chromadb>=0.5.0
+
+# Embeddings (HuggingFace sentence-transformers)
+sentence-transformers>=2.2.0
+
+# Utilities
+numpy>=1.24.0