memento-brain-memory 0.0.1__tar.gz

memento_brain_memory-0.0.1/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Node
+node_modules/
+.next/
+
+# IDE
+.DS_Store
+.vscode/
+.idea/
+
+# Env
+.env
+.env.local
+
+# Install script artifacts
+.venv-embedding/
+
+# DB
+*.sqlite
+*.db
+
+# Logs
+*.log
+
+# OS
+Thumbs.db
+.env
+.claude/

memento_brain_memory-0.0.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: memento-brain-memory
+Version: 0.0.1
+Summary: MCP Memory Server — personal AI memory powered by Memento data
+Project-URL: Homepage, https://github.com/ddong8/memento
+Project-URL: Repository, https://github.com/ddong8/memento
+Project-URL: Issues, https://github.com/ddong8/memento/issues
+Author: ddong8
+License: MIT
+Keywords: ai,claude,knowledge-graph,mcp,memento,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.26
+Requires-Dist: openai>=1.30
+Requires-Dist: pgvector>=0.3
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Description-Content-Type: text/markdown
+
+# Memento MCP Server
+
+Personal AI memory powered by your Memento data.
+
+## Usage
+
+```bash
+pip install memento-brain-memory
+memento-memory --db-url postgresql+asyncpg://user:pass@host:port/memento
+```
+
+## Claude Code Configuration
+
+```json
+{
+  "mcpServers": {
+    "memento-memory": {
+      "command": "memento-memory",
+      "args": ["--db-url", "postgresql+asyncpg://postgres:postgres@localhost:5433/memento"]
+    }
+  }
+}
+```

memento_brain_memory-0.0.1/README.md

@@ -0,0 +1,23 @@
+# Memento MCP Server
+
+Personal AI memory powered by your Memento data.
+
+## Usage
+
+```bash
+pip install memento-brain-memory
+memento-memory --db-url postgresql+asyncpg://user:pass@host:port/memento
+```
+
+## Claude Code Configuration
+
+```json
+{
+  "mcpServers": {
+    "memento-memory": {
+      "command": "memento-memory",
+      "args": ["--db-url", "postgresql+asyncpg://postgres:postgres@localhost:5433/memento"]
+    }
+  }
+}
+```

memento_brain_memory-0.0.1/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""Memento MCP Server — personal AI memory for all tools."""

memento_brain_memory-0.0.1/mcp_server/__main__.py

@@ -0,0 +1,49 @@
+"""Entry point for the MCP Memory Server.
+
+Usage:
+  # Remote mode (recommended — no DB needed, works anywhere):
+  memento-memory --server https://report.ihasy.com --token YOUR_JWT_TOKEN
+
+  # Direct DB mode (local dev / self-hosted):
+  memento-memory --db-url postgresql+asyncpg://user:pass@host:port/memento
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Memento MCP Server — personal AI memory for all tools",
+    )
+    parser.add_argument("--server", help="Memento server URL (e.g. https://report.ihasy.com)")
+    parser.add_argument("--token", help="JWT token for authentication")
+    parser.add_argument("--db-url", help="PostgreSQL connection URL (for direct DB mode)")
+    args = parser.parse_args()
+
+    server_url = args.server or os.environ.get("MEMENTO_SERVER_URL")
+    token = args.token or os.environ.get("MEMENTO_SERVER_TOKEN")
+    db_url = args.db_url or os.environ.get("MEMENTO_DATABASE_URL")
+
+    from .server import mcp, init_server
+
+    if server_url and token:
+        init_server(server_url=server_url, token=token)
+    elif db_url:
+        init_server(db_url=db_url)
+    else:
+        print("Error: Either --server/--token or --db-url is required.", file=sys.stderr)
+        print("\nRemote mode (recommended):", file=sys.stderr)
+        print("  memento-memory --server https://report.ihasy.com --token YOUR_TOKEN", file=sys.stderr)
+        print("\nDirect DB mode:", file=sys.stderr)
+        print("  memento-memory --db-url postgresql+asyncpg://...", file=sys.stderr)
+        sys.exit(1)
+
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

memento_brain_memory-0.0.1/mcp_server/db.py

@@ -0,0 +1,150 @@
+"""Database connection for MCP server — connects directly to PostgreSQL."""
+
+from __future__ import annotations
+
+import os
+
+from sqlalchemy import (
+    BigInteger, Boolean, Date, DateTime, Float, ForeignKey, Index, Integer,
+    String, Text, UniqueConstraint, func,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+import uuid
+from datetime import date, datetime
+
+try:
+    from pgvector.sqlalchemy import Vector
+except ImportError:
+    Vector = None
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+# Minimal model definitions (mirror of server models, read-only)
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    email: Mapped[str] = mapped_column(String(320))
+    name: Mapped[str | None] = mapped_column(String(255))
+    role: Mapped[str] = mapped_column(String(20))
+    collector_token: Mapped[str | None] = mapped_column(String(64))
+
+
+class Machine(Base):
+    __tablename__ = "machines"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    name: Mapped[str] = mapped_column(String(255))
+    user_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("users.id"))
+
+
+class Tool(Base):
+    __tablename__ = "tools"
+    id: Mapped[str] = mapped_column(String(50), primary_key=True)
+    display_name: Mapped[str] = mapped_column(String(100))
+
+
+class Project(Base):
+    __tablename__ = "projects"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    slug: Mapped[str] = mapped_column(String(255))
+    title: Mapped[str] = mapped_column(String(500))
+    tool_id: Mapped[str | None] = mapped_column(ForeignKey("tools.id"))
+    source_path: Mapped[str | None] = mapped_column(Text)
+
+
+class Document(Base):
+    __tablename__ = "documents"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    tool_id: Mapped[str] = mapped_column(String(50))
+    project_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("projects.id"))
+    machine_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("machines.id"))
+    relative_path: Mapped[str] = mapped_column(Text)
+    category: Mapped[str] = mapped_column(String(50))
+    content_type: Mapped[str] = mapped_column(String(50))
+    title: Mapped[str | None] = mapped_column(Text)
+    content: Mapped[str | None] = mapped_column(Text)
+    content_hash: Mapped[str] = mapped_column(String(64))
+    file_size_bytes: Mapped[int] = mapped_column(BigInteger)
+    metadata_: Mapped[dict] = mapped_column("metadata", JSONB, default=dict)
+    ai_summary: Mapped[str | None] = mapped_column(Text)
+    synced_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class ConversationMessage(Base):
+    __tablename__ = "conversation_messages"
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    document_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("documents.id"))
+    line_number: Mapped[int] = mapped_column(Integer)
+    message_type: Mapped[str | None] = mapped_column(String(50))
+    role: Mapped[str | None] = mapped_column(String(20))
+    content: Mapped[str | None] = mapped_column(Text)
+    metadata_: Mapped[dict | None] = mapped_column("metadata", JSONB)
+    timestamp: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class DailySummary(Base):
+    __tablename__ = "daily_summaries"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    summary_date: Mapped[date] = mapped_column(Date)
+    tool_id: Mapped[str | None] = mapped_column(String(50))
+    title: Mapped[str] = mapped_column(Text)
+    summary: Mapped[str] = mapped_column(Text)
+    highlights: Mapped[dict | None] = mapped_column(JSONB)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class DocumentEmbedding(Base):
+    __tablename__ = "document_embeddings"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    document_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("documents.id"))
+    chunk_index: Mapped[int] = mapped_column(Integer)
+    chunk_text: Mapped[str] = mapped_column(Text)
+    embedding = mapped_column(Vector(1024) if Vector else Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class KnowledgeEntity(Base):
+    __tablename__ = "knowledge_entities"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    user_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("users.id"))
+    name: Mapped[str] = mapped_column(Text)
+    entity_type: Mapped[str] = mapped_column(String(50))
+    summary: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class KnowledgeRelation(Base):
+    __tablename__ = "knowledge_relations"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    source_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("knowledge_entities.id"))
+    target_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("knowledge_entities.id"))
+    relation_type: Mapped[str] = mapped_column(String(50))
+    strength: Mapped[float] = mapped_column(Float)
+
+
+class KnowledgeObservation(Base):
+    __tablename__ = "knowledge_observations"
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+    entity_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("knowledge_entities.id"))
+    content: Mapped[str] = mapped_column(Text)
+    source_document_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("documents.id"))
+    observed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+def get_db_url() -> str:
+    return os.environ.get(
+        "MEMENTO_DATABASE_URL",
+        "postgresql+asyncpg://postgres:postgres@localhost:5433/memento",
+    )
+
+
+def create_engine_and_session(db_url: str | None = None) -> async_sessionmaker[AsyncSession]:
+    url = db_url or get_db_url()
+    engine = create_async_engine(url, pool_size=5, max_overflow=10)
+    return async_sessionmaker(engine, expire_on_commit=False)

memento_brain_memory-0.0.1/mcp_server/graph.py

@@ -0,0 +1,162 @@
+"""Knowledge graph operations — entity context and observation storage."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import func, select, or_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .db import (
+    Document, KnowledgeEntity, KnowledgeObservation, KnowledgeRelation,
+    Machine, Project,
+)
+
+
+async def get_entity_context(
+    db: AsyncSession, project_name: str, user_id: uuid.UUID | None = None,
+) -> str:
+    """Build comprehensive project context from knowledge graph + documents."""
+    parts = []
+
+    # 1. Find the project
+    project_q = select(Project).where(
+        or_(
+            Project.title.ilike(f"%{project_name}%"),
+            Project.slug.ilike(f"%{project_name}%"),
+        )
+    ).limit(1)
+    project = (await db.execute(project_q)).scalar_one_or_none()
+
+    if project:
+        parts.append(f"# Project: {project.title}")
+        parts.append(f"**Tool**: {project.tool_id}")
+        if project.source_path:
+            parts.append(f"**Path**: `{project.source_path}`")
+
+        # Get document stats
+        doc_stats = await db.execute(
+            select(Document.category, func.count())
+            .where(Document.project_id == project.id)
+            .group_by(Document.category)
+        )
+        stats = {r[0]: r[1] for r in doc_stats.all()}
+        if stats:
+            parts.append("\n## Documents")
+            for cat, count in sorted(stats.items()):
+                parts.append(f"- {cat}: {count}")
+
+        # Get recent conversation titles
+        recent = await db.execute(
+            select(Document.title, Document.synced_at)
+            .where(Document.project_id == project.id, Document.category == "conversation")
+            .order_by(Document.synced_at.desc())
+            .limit(5)
+        )
+        convos = recent.all()
+        if convos:
+            parts.append("\n## Recent Conversations")
+            for title, synced_at in convos:
+                parts.append(f"- {title} ({synced_at.strftime('%Y-%m-%d')})")
+
+        # Get memory/plan files
+        memory_docs = await db.execute(
+            select(Document.title, Document.content, Document.category)
+            .where(
+                Document.project_id == project.id,
+                Document.category.in_(["memory", "plan", "identity"]),
+            )
+            .order_by(Document.synced_at.desc())
+            .limit(5)
+        )
+        for title, content, cat in memory_docs.all():
+            parts.append(f"\n## {cat.title()}: {title}")
+            parts.append((content or "")[:1000])
+
+    # 2. Knowledge graph entities matching the project name
+    entity_filter = [KnowledgeEntity.name.ilike(f"%{project_name}%")]
+    if user_id:
+        entity_filter.append(
+            or_(KnowledgeEntity.user_id == user_id, KnowledgeEntity.user_id.is_(None))
+        )
+
+    entities = await db.execute(
+        select(KnowledgeEntity).where(*entity_filter).limit(10)
+    )
+    entity_list = entities.scalars().all()
+
+    if entity_list:
+        parts.append("\n## Knowledge Graph")
+        for entity in entity_list:
+            parts.append(f"\n### {entity.name} ({entity.entity_type})")
+            if entity.summary:
+                parts.append(entity.summary)
+
+            # Relations
+            rels = await db.execute(
+                select(KnowledgeRelation, KnowledgeEntity)
+                .join(KnowledgeEntity, KnowledgeRelation.target_id == KnowledgeEntity.id)
+                .where(KnowledgeRelation.source_id == entity.id)
+                .limit(10)
+            )
+            for rel, target in rels.all():
+                parts.append(f"  → {rel.relation_type} → **{target.name}** ({target.entity_type})")
+
+            # Observations
+            obs = await db.execute(
+                select(KnowledgeObservation.content, KnowledgeObservation.observed_at)
+                .where(KnowledgeObservation.entity_id == entity.id)
+                .order_by(KnowledgeObservation.observed_at.desc())
+                .limit(5)
+            )
+            for content, obs_at in obs.all():
+                date_str = obs_at.strftime("%Y-%m-%d") if obs_at else ""
+                parts.append(f"  - [{date_str}] {content}")
+
+    if not parts:
+        return f"No context found for '{project_name}'."
+
+    return "\n".join(parts)
+
+
+async def store_observation(
+    db: AsyncSession,
+    content: str,
+    entity_name: str | None = None,
+    entity_type: str = "concept",
+    user_id: uuid.UUID | None = None,
+) -> str:
+    """Store a new observation, creating the entity if needed."""
+    if not entity_name:
+        # Auto-extract entity from content (simple heuristic)
+        words = content.split()
+        entity_name = " ".join(words[:3]) if len(words) > 3 else content[:50]
+
+    # Find or create entity
+    q = select(KnowledgeEntity).where(
+        KnowledgeEntity.name == entity_name,
+        KnowledgeEntity.entity_type == entity_type,
+    )
+    if user_id:
+        q = q.where(KnowledgeEntity.user_id == user_id)
+
+    entity = (await db.execute(q)).scalar_one_or_none()
+    if not entity:
+        entity = KnowledgeEntity(
+            user_id=user_id,
+            name=entity_name,
+            entity_type=entity_type,
+        )
+        db.add(entity)
+        await db.flush()
+
+    # Add observation
+    obs = KnowledgeObservation(
+        entity_id=entity.id,
+        content=content,
+    )
+    db.add(obs)
+    await db.flush()
+
+    return f"Stored observation for entity '{entity_name}' ({entity_type}): {content[:100]}"

memento_brain_memory-0.0.1/mcp_server/remote_client.py

@@ -0,0 +1,143 @@
+"""Remote HTTP client — calls Memento server REST API instead of direct DB access.
+
+This lets the MCP server run on any machine without needing PostgreSQL connection.
+Only needs: server URL + user's collector token (JWT or collector_token).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+
+import httpx
+
+logger = logging.getLogger("mcp_memory.remote")
+
+
+class RemoteClient:
+    """HTTP client for Memento server API."""
+
+    def __init__(self, server_url: str, token: str):
+        self.base_url = server_url.rstrip("/")
+        self.token = token
+        self._jwt: str | None = None
+        self._jwt_time: float = 0  # When JWT was obtained
+
+    async def _ensure_jwt(self) -> str:
+        """Get JWT token with auto-renewal (re-exchange after 20 hours)."""
+        import time
+        # Renew if JWT older than 20 hours (tokens expire at 24h)
+        if self._jwt and (time.time() - self._jwt_time) < 72000:
+            return self._jwt
+        self._jwt = None  # Force re-exchange
+        async with httpx.AsyncClient(timeout=10) as client:
+            # Try as JWT directly
+            resp = await client.get(
+                f"{self.base_url}/api/auth/me",
+                headers={"Authorization": f"Bearer {self.token}"},
+            )
+            if resp.status_code == 200:
+                self._jwt = self.token
+                self._jwt_time = time.time()
+                return self._jwt
+
+            # Try token-exchange (collector_token → JWT)
+            resp = await client.post(
+                f"{self.base_url}/api/auth/token-exchange",
+                headers={"X-Collector-Token": self.token},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                self._jwt = data["access_token"]
+                self._jwt_time = time.time()
+                logger.info("JWT obtained via token-exchange")
+                return self._jwt
+
+        raise RuntimeError(
+            f"Invalid token. Get a valid token from {self.base_url}"
+        )
+
+    async def _get(self, path: str, params: dict | None = None) -> dict | list:
+        jwt = await self._ensure_jwt()
+        async with httpx.AsyncClient(timeout=30) as client:
+            resp = await client.get(
+                f"{self.base_url}{path}",
+                params=params,
+                headers={"Authorization": f"Bearer {jwt}"},
+            )
+            # Auto-retry on 401 (JWT expired)
+            if resp.status_code == 401:
+                self._jwt = None
+                jwt = await self._ensure_jwt()
+                resp = await client.get(
+                    f"{self.base_url}{path}",
+                    params=params,
+                    headers={"Authorization": f"Bearer {jwt}"},
+                )
+            resp.raise_for_status()
+            return resp.json()
+
+    async def _post(self, path: str, json_data: dict | None = None) -> dict:
+        jwt = await self._ensure_jwt()
+        async with httpx.AsyncClient(timeout=30) as client:
+            resp = await client.post(
+                f"{self.base_url}{path}",
+                json=json_data,
+                headers={"Authorization": f"Bearer {jwt}"},
+            )
+            if resp.status_code == 401:
+                self._jwt = None
+                jwt = await self._ensure_jwt()
+                resp = await client.post(
+                    f"{self.base_url}{path}",
+                    json=json_data,
+                    headers={"Authorization": f"Bearer {jwt}"},
+                )
+            resp.raise_for_status()
+            return resp.json()
+
+    # --- Memory search ---
+    async def search(self, query: str, limit: int = 5, tool_filter: str | None = None) -> list[dict]:
+        params = {"q": query, "limit": limit}
+        if tool_filter:
+            params["tool"] = tool_filter
+        result = await self._get("/api/search", params)
+        return result.get("results", []) if isinstance(result, dict) else []
+
+    # --- Projects ---
+    async def list_projects(self) -> list[dict]:
+        return await self._get("/api/projects")
+
+    async def get_project(self, project_id: str) -> dict:
+        return await self._get(f"/api/projects/{project_id}")
+
+    # --- Documents ---
+    async def get_document(self, doc_id: str) -> dict:
+        return await self._get(f"/api/documents/{doc_id}")
+
+    # --- Conversations ---
+    async def get_conversation_messages(self, doc_id: str, limit: int = 50) -> dict:
+        return await self._get(f"/api/conversations/{doc_id}/messages", {"limit": limit})
+
+    # --- Daily ---
+    async def get_daily(self, date_str: str) -> dict:
+        from datetime import datetime, timezone, timedelta
+        tz = int(datetime.now(timezone.utc).astimezone().utcoffset().total_seconds() // 60)
+        return await self._get(f"/api/daily/{date_str}", {"tz_offset": -tz})
+
+    async def get_daily_dates(self, days: int = 30) -> list[dict]:
+        return await self._get("/api/daily", {"days": days})
+
+    # --- Dashboard ---
+    async def get_dashboard(self) -> dict:
+        return await self._get("/api/dashboard")
+
+    # --- Tools ---
+    async def get_tools(self) -> list[dict]:
+        return await self._get("/api/tools")
+
+    async def get_tool_files(self, tool_id: str, category: str | None = None) -> list[dict]:
+        params = {}
+        if category:
+            params["category"] = category
+        return await self._get(f"/api/tools/{tool_id}/files", params)

memento_brain_memory-0.0.1/mcp_server/search.py

@@ -0,0 +1,254 @@
+"""Hybrid search engine — semantic (pgvector) + full-text (tsvector) + knowledge graph."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import func, select, text, or_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .db import Document, DocumentEmbedding, KnowledgeEntity, KnowledgeObservation, Machine
+
+logger = logging.getLogger("mcp_memory.search")
+
+
+_local_model = None
+_model_lock = None
+
+
+def _get_local_model():
+    """Load BGE-M3 model lazily."""
+    global _local_model, _model_lock
+    import threading
+    if _model_lock is None:
+        _model_lock = threading.Lock()
+    if _local_model is not None:
+        return _local_model
+    with _model_lock:
+        if _local_model is not None:
+            return _local_model
+        try:
+            from sentence_transformers import SentenceTransformer
+            _local_model = SentenceTransformer("BAAI/bge-m3")
+            return _local_model
+        except Exception:
+            return None
+
+
+async def _get_embedding(query: str) -> list[float] | None:
+    """Generate embedding for a query. Tries local BGE-M3 first, then remote API."""
+    import asyncio
+    # Try local model
+    model = _get_local_model()
+    if model is not None:
+        try:
+            embedding = await asyncio.to_thread(
+                lambda: model.encode(query, normalize_embeddings=True).tolist()
+            )
+            return embedding
+        except Exception:
+            pass
+
+    # Fallback: remote API
+    import os
+    api_key = os.environ.get("MEMENTO_EMBEDDING_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    base_url = os.environ.get("MEMENTO_EMBEDDING_BASE_URL")
+    emb_model = os.environ.get("MEMENTO_EMBEDDING_MODEL", "text-embedding-v4")
+    if not api_key or not base_url:
+        return None
+    try:
+        import openai
+        client = openai.AsyncOpenAI(api_key=api_key, base_url=base_url)
+        response = await client.embeddings.create(input=query, model=emb_model)
+        return response.data[0].embedding
+    except Exception as e:
+        logger.debug("Embedding generation failed: %s", e)
+        return None
+
+
+async def _semantic_search(
+    db: AsyncSession, query: str, limit: int, user_machine_ids: list[uuid.UUID] | None,
+    tool_filter: str | None, cutoff: datetime | None,
+) -> list[dict]:
+    """Search via pgvector cosine similarity."""
+    embedding = await _get_embedding(query)
+    if embedding is None:
+        return []
+
+    try:
+        from pgvector.sqlalchemy import Vector
+    except ImportError:
+        return []
+
+    q = (
+        select(
+            DocumentEmbedding.chunk_text,
+            DocumentEmbedding.document_id,
+            Document.title,
+            Document.tool_id,
+            Document.relative_path,
+            Document.synced_at,
+            DocumentEmbedding.embedding.cosine_distance(embedding).label("distance"),
+        )
+        .join(Document, DocumentEmbedding.document_id == Document.id)
+        .order_by("distance")
+        .limit(limit)
+    )
+    if user_machine_ids is not None:
+        q = q.where(Document.machine_id.in_(user_machine_ids))
+    if tool_filter:
+        q = q.where(Document.tool_id == tool_filter)
+    if cutoff:
+        q = q.where(Document.synced_at >= cutoff)
+
+    result = await db.execute(q)
+    return [
+        {
+            "content": row.chunk_text,
+            "title": row.title or row.relative_path,
+            "tool_id": row.tool_id,
+            "relative_path": row.relative_path,
+            "date": row.synced_at.strftime("%Y-%m-%d") if row.synced_at else "",
+            "score": 1.0 - row.distance,  # Convert distance to similarity
+            "source": "semantic",
+        }
+        for row in result.all()
+    ]
+
+
+async def _fulltext_search(
+    db: AsyncSession, query: str, limit: int, user_machine_ids: list[uuid.UUID] | None,
+    tool_filter: str | None, cutoff: datetime | None,
+) -> list[dict]:
+    """Search via PostgreSQL LIKE (simple but effective)."""
+    pattern = f"%{query}%"
+    q = (
+        select(Document.title, Document.tool_id, Document.relative_path,
+               Document.content, Document.synced_at)
+        .where(
+            or_(
+                Document.content.ilike(pattern),
+                Document.title.ilike(pattern),
+            )
+        )
+        .order_by(Document.synced_at.desc())
+        .limit(limit)
+    )
+    if user_machine_ids is not None:
+        q = q.where(Document.machine_id.in_(user_machine_ids))
+    if tool_filter:
+        q = q.where(Document.tool_id == tool_filter)
+    if cutoff:
+        q = q.where(Document.synced_at >= cutoff)
+
+    result = await db.execute(q)
+    results = []
+    for row in result.all():
+        # Extract relevant snippet around the match
+        content = row.content or ""
+        idx = content.lower().find(query.lower())
+        if idx >= 0:
+            start = max(0, idx - 200)
+            end = min(len(content), idx + len(query) + 300)
+            snippet = ("..." if start > 0 else "") + content[start:end] + ("..." if end < len(content) else "")
+        else:
+            snippet = content[:500]
+
+        results.append({
+            "content": snippet,
+            "title": row.title or row.relative_path,
+            "tool_id": row.tool_id,
+            "relative_path": row.relative_path,
+            "date": row.synced_at.strftime("%Y-%m-%d") if row.synced_at else "",
+            "score": 0.5,  # Fixed score for full-text matches
+            "source": "fulltext",
+        })
+    return results
+
+
+async def _graph_search(
+    db: AsyncSession, query: str, limit: int, user_id: uuid.UUID | None,
+) -> list[dict]:
+    """Search via knowledge graph entity matching."""
+    # Find matching entities
+    q = (
+        select(KnowledgeEntity.name, KnowledgeEntity.entity_type, KnowledgeEntity.summary)
+        .where(KnowledgeEntity.name.ilike(f"%{query}%"))
+        .limit(5)
+    )
+    if user_id:
+        q = q.where(or_(KnowledgeEntity.user_id == user_id, KnowledgeEntity.user_id.is_(None)))
+
+    entities = await db.execute(q)
+    entity_rows = entities.all()
+    if not entity_rows:
+        return []
+
+    results = []
+    for name, etype, summary in entity_rows:
+        # Get recent observations
+        obs_q = (
+            select(KnowledgeObservation.content, KnowledgeObservation.observed_at)
+            .join(KnowledgeEntity, KnowledgeObservation.entity_id == KnowledgeEntity.id)
+            .where(KnowledgeEntity.name == name)
+            .order_by(KnowledgeObservation.observed_at.desc())
+            .limit(3)
+        )
+        obs_result = await db.execute(obs_q)
+        observations = [f"- {r.content}" for r in obs_result.all()]
+
+        content = f"**{name}** ({etype})\n"
+        if summary:
+            content += f"{summary}\n"
+        if observations:
+            content += "\nRecent observations:\n" + "\n".join(observations)
+
+        results.append({
+            "content": content,
+            "title": name,
+            "tool_id": "knowledge_graph",
+            "relative_path": f"entity/{etype}/{name}",
+            "date": "",
+            "score": 0.7,
+            "source": "graph",
+        })
+    return results
+
+
+async def hybrid_search(
+    db: AsyncSession,
+    query: str,
+    limit: int = 5,
+    tool_filter: str | None = None,
+    days: int | None = None,
+    user_id: uuid.UUID | None = None,
+) -> list[dict]:
+    """Combined semantic + full-text + graph search with deduplication."""
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days) if days else None
+
+    # Get user's machine IDs for data isolation
+    user_machine_ids = None
+    if user_id:
+        result = await db.execute(select(Machine.id).where(Machine.user_id == user_id))
+        user_machine_ids = [r[0] for r in result.all()]
+
+    # Run all search strategies
+    semantic_results = await _semantic_search(db, query, limit * 2, user_machine_ids, tool_filter, cutoff)
+    fulltext_results = await _fulltext_search(db, query, limit * 2, user_machine_ids, tool_filter, cutoff)
+    graph_results = await _graph_search(db, query, limit, user_id)
+
+    # Merge and deduplicate by relative_path
+    seen = set()
+    merged = []
+    for r in sorted(semantic_results + fulltext_results + graph_results, key=lambda x: -x["score"]):
+        key = r["relative_path"]
+        if key in seen:
+            continue
+        seen.add(key)
+        merged.append(r)
+        if len(merged) >= limit:
+            break
+
+    return merged

memento_brain_memory-0.0.1/mcp_server/server.py

@@ -0,0 +1,415 @@
+"""MCP Memory Server — exposes personal AI memory via Model Context Protocol.
+
+Two modes:
+  - Remote (--server + --token): calls Memento server REST API. No DB needed.
+  - Direct (--db-url): connects directly to PostgreSQL. For local dev/self-hosted.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime, timedelta, timezone
+
+from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger("mcp_memory")
+
+mcp = FastMCP(
+    "Memento",
+    instructions="Personal AI memory — search conversations, recall knowledge, explore project context from your Memento data.",
+)
+
+# Initialized on startup
+_remote = None  # RemoteClient for HTTP mode
+_session_factory = None  # SQLAlchemy session factory for DB mode
+
+
+def init_server(server_url: str | None = None, token: str | None = None, db_url: str | None = None):
+    """Initialize the MCP server. Either (server_url + token) or db_url."""
+    global _remote, _session_factory
+    if server_url and token:
+        from .remote_client import RemoteClient
+        _remote = RemoteClient(server_url, token)
+        logger.info("MCP Memory Server initialized in remote mode: %s", server_url)
+    elif db_url:
+        from .db import create_engine_and_session
+        _session_factory = create_engine_and_session(db_url)
+        logger.info("MCP Memory Server initialized in direct DB mode")
+    else:
+        raise ValueError("Either --server/--token or --db-url required")
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def memory_search(
+    query: str,
+    limit: int = 5,
+    tool_filter: str | None = None,
+    days: int | None = None,
+) -> str:
+    """Search your personal AI memory using semantic + full-text hybrid search.
+
+    Use this to find past conversations, decisions, solutions, and knowledge
+    from all your AI tools (Claude Code, Cursor, Codex, Windsurf, etc.).
+
+    Args:
+        query: Natural language search query
+        limit: Max results to return (default 5)
+        tool_filter: Optional tool filter (claude_code, codex, cursor, antigravity, openclaw, obsidian)
+        days: Optional time filter — only search last N days
+    """
+    if _remote:
+        try:
+            results = await _remote.search(query, limit=limit, tool_filter=tool_filter)
+        except Exception as e:
+            return f"Search failed: {e}"
+        if not results:
+            return "No matching memories found."
+        parts = []
+        for i, r in enumerate(results, 1):
+            title = r.get('title') or r.get('relative_path', 'Untitled')
+            snippet = r.get('snippet', '') or ''
+            parts.append(
+                f"## Result {i}: {title} ({r.get('tool_id', '')})\n"
+                f"**Source**: {r.get('relative_path', '')}\n"
+                f"**Date**: {(r.get('synced_at') or '')[:10]}\n\n"
+                f"{snippet}\n"
+            )
+        return "\n---\n\n".join(parts)
+
+    # Direct DB mode
+    from .search import hybrid_search
+    async with _session_factory() as db:
+        results = await hybrid_search(db, query, limit=limit, tool_filter=tool_filter, days=days)
+        if not results:
+            return "No matching memories found."
+        parts = []
+        for i, r in enumerate(results, 1):
+            parts.append(
+                f"## Result {i}: {r['title']} ({r['tool_id']})\n"
+                f"**Source**: {r['relative_path']}\n"
+                f"**Date**: {r['date']}\n\n"
+                f"{r['content']}\n"
+            )
+        return "\n---\n\n".join(parts)
+
+
+@mcp.tool()
+async def memory_recall(
+    category: str = "conversation",
+    project: str | None = None,
+    days: int = 7,
+    limit: int = 10,
+    date: str | None = None,
+) -> str:
+    """Recall recent memories by category, project, and optional date.
+
+    Args:
+        category: Memory category (conversation, memory, identity, plan, config, learning, skill, note)
+        project: Optional project name filter
+        days: How far back to look (default 7 days, ignored if date given)
+        limit: Max items to return
+        date: Optional specific date (YYYY-MM-DD), overrides days
+    """
+    if _remote:
+        # If specific date given, use daily endpoint
+        if date:
+            try:
+                data = await _remote.get_daily(date)
+                conversations = data.get("overview", {}).get("conversations", [])
+                if not conversations:
+                    return f"No conversations on {date}."
+                parts = [f"# Conversations on {date}\n"]
+                for c in conversations[:limit]:
+                    title = c.get("title") or c.get("id", "")[:8]
+                    u = c.get("user_messages", 0)
+                    a = c.get("assistant_messages", 0)
+                    parts.append(f"- [{c.get('tool_id', '')}] **{title}** ({u}↑ {a}↓)")
+                return "\n".join(parts)
+            except Exception as e:
+                return f"Could not load conversations for {date}: {e}"
+
+        # Otherwise use search-style: list recent files of category
+        try:
+            tools = await _remote.get_tools()
+        except Exception as e:
+            return f"Failed to list tools: {e}"
+
+        from datetime import datetime as _dt
+        cutoff_str = (_dt.utcnow() - timedelta(days=days)).isoformat()
+        all_files = []
+        for tool in tools:
+            try:
+                files = await _remote.get_tool_files(tool.get("id", ""), category=category)
+                for f in files:
+                    f["_tool_id"] = tool.get("id", "")
+                    all_files.append(f)
+            except Exception:
+                continue
+
+        # Filter by date and project
+        filtered = [f for f in all_files if (f.get("synced_at") or "") >= cutoff_str]
+        if project:
+            filtered = [f for f in filtered if project.lower() in (f.get("relative_path") or "").lower()]
+
+        # Sort by synced_at desc
+        filtered.sort(key=lambda f: f.get("synced_at", ""), reverse=True)
+
+        if not filtered:
+            return f"No {category} memories in last {days} days."
+
+        parts = [f"# Recent {category} (last {days} days)\n"]
+        for f in filtered[:limit]:
+            title = f.get("title") or f.get("relative_path", "")
+            d = (f.get("synced_at") or "")[:10]
+            parts.append(f"- [{f['_tool_id']}] **{title}** — {d}")
+        return "\n".join(parts)
+
+    # Direct DB mode
+    from sqlalchemy import select
+    from .db import Document, Project
+    async with _session_factory() as db:
+        cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+        q = (
+            select(Document.title, Document.tool_id, Document.relative_path,
+                   Document.content, Document.synced_at)
+            .where(Document.category == category, Document.synced_at >= cutoff)
+            .order_by(Document.synced_at.desc())
+            .limit(limit)
+        )
+        if project:
+            q = q.join(Project, Document.project_id == Project.id).where(
+                Project.title.ilike(f"%{project}%")
+            )
+        result = await db.execute(q)
+        rows = result.all()
+        if not rows:
+            return f"No {category} memories found in the last {days} days."
+        parts = []
+        for title, tool_id, path, content, synced_at in rows:
+            preview = (content or "")[:500]
+            parts.append(
+                f"### {title or path} ({tool_id})\n"
+                f"*{synced_at.strftime('%Y-%m-%d %H:%M')}*\n\n"
+                f"{preview}{'...' if len(content or '') > 500 else ''}\n"
+            )
+        return "\n---\n\n".join(parts)
+
+
+@mcp.tool()
+async def memory_context(project_name: str) -> str:
+    """Get comprehensive project context — recent conversations, plans, and memory files.
+
+    Use this when starting work on a project to load all relevant context.
+
+    Args:
+        project_name: Project name to look up
+    """
+    if _remote:
+        projects = await _remote.list_projects()
+        matched = [p for p in projects if project_name.lower() in (p.get("title", "") or "").lower()]
+        if not matched:
+            return f"No project found matching '{project_name}'."
+        project = await _remote.get_project(matched[0]["id"])
+        parts = [f"# Project: {project.get('title', project_name)}"]
+        parts.append(f"**Tool**: {project.get('tool_id', '')}")
+        if project.get("source_path"):
+            parts.append(f"**Path**: `{project['source_path']}`")
+        docs = project.get("documents", [])
+        if docs:
+            parts.append(f"\n## Documents ({len(docs)})")
+            for d in docs[:10]:
+                parts.append(f"- [{d.get('category', '')}] {d.get('title', d.get('relative_path', ''))}")
+        return "\n".join(parts)
+
+    # Direct DB mode
+    from .graph import get_entity_context
+    async with _session_factory() as db:
+        return await get_entity_context(db, project_name)
+
+
+@mcp.tool()
+async def memory_store(
+    content: str,
+    entity_name: str | None = None,
+    entity_type: str = "concept",
+) -> str:
+    """Store a new observation or fact in your personal memory.
+
+    Use this to save important decisions, learnings, or context for later recall.
+
+    Args:
+        content: The fact or observation to remember
+        entity_name: Optional entity this relates to (e.g. project name, technology)
+        entity_type: Entity type (project/tool/concept/person/technology)
+    """
+    if _remote:
+        return f"Noted: {content[:200]}... (remote storage coming soon)"
+
+    from .graph import store_observation
+    async with _session_factory() as db:
+        result = await store_observation(db, content, entity_name=entity_name, entity_type=entity_type)
+        await db.commit()
+        return result
+
+
+@mcp.tool()
+async def daily_summary(date_str: str | None = None) -> str:
+    """Get daily activity summary for a specific date.
+
+    Args:
+        date_str: Date in YYYY-MM-DD format (default: today)
+    """
+    target = date_str or date.today().isoformat()
+
+    if _remote:
+        try:
+            data = await _remote.get_daily(target)
+            total = data.get("total_messages", 0)
+            if total == 0:
+                return f"No activity recorded on {target}."
+
+            tool_stats = data.get("overview", {}).get("tool_stats", {})
+            conversations = data.get("overview", {}).get("conversations", [])
+            summaries = data.get("summaries", [])
+
+            parts = [f"# Activity Summary — {target}", f"\n**Total messages**: {total}\n"]
+
+            # Tool breakdown
+            parts.append("## Tools")
+            for tool, count in sorted(tool_stats.items(), key=lambda x: -x[1]):
+                parts.append(f"- **{tool}**: {count} messages")
+
+            # Top conversations (real titles, not just counts)
+            if conversations:
+                parts.append("\n## Top Conversations")
+                for c in conversations[:10]:
+                    title = c.get("title") or c.get("id", "")[:8]
+                    u = c.get("user_messages", 0)
+                    a = c.get("assistant_messages", 0)
+                    parts.append(f"- [{c.get('tool_id', '')}] **{title}** ({u}↑ {a}↓)")
+
+            # AI summary if exists
+            if summaries:
+                for s in summaries:
+                    parts.append(f"\n## {s.get('title', 'AI Summary')}\n{s.get('summary', '')}")
+            else:
+                parts.append("\n*No AI summary yet. Generate one at https://report.ihasy.com/daily/" + target + "*")
+
+            return "\n".join(parts)
+        except Exception as e:
+            return f"Could not load daily summary for {target}: {e}"
+
+    # Direct DB mode
+    from sqlalchemy import select, func, cast, Date as SqlDate
+    from .db import DailySummary, ConversationMessage, Document
+    target_date = date.fromisoformat(target)
+    async with _session_factory() as db:
+        result = await db.execute(
+            select(DailySummary).where(
+                DailySummary.summary_date == target_date, DailySummary.tool_id.is_(None)
+            )
+        )
+        summary = result.scalar_one_or_none()
+        if summary:
+            return f"# AI Daily Summary — {target}\n\n{summary.summary}"
+
+        tz_cst = timezone(timedelta(hours=8))
+        day_start = datetime(target_date.year, target_date.month, target_date.day, tzinfo=tz_cst)
+        day_end = day_start + timedelta(days=1)
+        msg_result = await db.execute(
+            select(Document.tool_id, func.count())
+            .join(ConversationMessage, ConversationMessage.document_id == Document.id)
+            .where(ConversationMessage.timestamp >= day_start, ConversationMessage.timestamp < day_end,
+                   ConversationMessage.role.in_(["user", "assistant"]))
+            .group_by(Document.tool_id)
+        )
+        stats = {r[0]: r[1] for r in msg_result.all()}
+        if not stats:
+            return f"No activity recorded on {target}."
+        total = sum(stats.values())
+        lines = [f"# Activity Summary — {target}", f"Total messages: {total}\n"]
+        for tool, count in sorted(stats.items(), key=lambda x: -x[1]):
+            lines.append(f"- **{tool}**: {count} messages")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Resources
+# ---------------------------------------------------------------------------
+
+@mcp.resource("memory://projects")
+async def list_projects() -> str:
+    """List all projects with document counts."""
+    if _remote:
+        projects = await _remote.list_projects()
+        if not projects:
+            return "No projects found."
+        lines = ["# Projects\n"]
+        for p in projects[:50]:
+            lines.append(f"- **{p.get('title', '')}** ({p.get('tool_id', '')}) — {p.get('document_count', 0)} files")
+        return "\n".join(lines)
+
+    from sqlalchemy import select, func
+    from .db import Project, Document
+    async with _session_factory() as db:
+        result = await db.execute(
+            select(Project.title, Project.tool_id, Project.source_path,
+                   func.count(Document.id).label("doc_count"))
+            .outerjoin(Document, Document.project_id == Project.id)
+            .group_by(Project.id)
+            .order_by(func.count(Document.id).desc())
+            .limit(50)
+        )
+        rows = result.all()
+        if not rows:
+            return "No projects found."
+        lines = ["# Projects\n"]
+        for title, tool_id, source_path, count in rows:
+            lines.append(f"- **{title}** ({tool_id}) — {count} files — `{source_path or ''}`")
+        return "\n".join(lines)
+
+
+@mcp.resource("memory://projects/{name}")
+async def get_project(name: str) -> str:
+    """Get project details."""
+    return await memory_context(name)
+
+
+@mcp.resource("memory://identity/{tool}")
+async def get_identity(tool: str) -> str:
+    """Get tool identity files (AGENTS.md, SOUL.md, etc.)."""
+    if _remote:
+        files = await _remote.get_tool_files(tool, category="identity")
+        if not files:
+            return f"No identity files found for {tool}."
+        parts = []
+        for f in files:
+            doc = await _remote.get_document(f["id"])
+            parts.append(f"## {doc.get('title', '')}\n\n{doc.get('content', '(empty)')}")
+        return "\n\n---\n\n".join(parts)
+
+    from sqlalchemy import select
+    from .db import Document
+    async with _session_factory() as db:
+        result = await db.execute(
+            select(Document.title, Document.content)
+            .where(Document.tool_id == tool, Document.category == "identity")
+            .order_by(Document.synced_at.desc())
+        )
+        rows = result.all()
+        if not rows:
+            return f"No identity files found for {tool}."
+        parts = []
+        for title, content in rows:
+            parts.append(f"## {title}\n\n{content or '(empty)'}")
+        return "\n\n---\n\n".join(parts)
+
+
+@mcp.resource("memory://daily/{date_str}")
+async def get_daily(date_str: str) -> str:
+    """Get daily report for a specific date."""
+    return await daily_summary(date_str)

memento_brain_memory-0.0.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "memento-brain-memory"
+version = "0.0.1"
+description = "MCP Memory Server — personal AI memory powered by Memento data"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "ddong8"}]
+keywords = ["memento", "mcp", "memory", "ai", "claude", "knowledge-graph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.26",
+    "asyncpg>=0.30",
+    "sqlalchemy[asyncio]>=2.0",
+    "pgvector>=0.3",
+    "openai>=1.30",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/ddong8/memento"
+Repository = "https://github.com/ddong8/memento"
+Issues = "https://github.com/ddong8/memento/issues"
+
+[project.scripts]
+# Primary — matches pkg name
+memento-brain-memory = "mcp_server.__main__:main"
+# Short alias — back-compat and convenience
+memento-memory = "mcp_server.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mcp_server"]