mnemon-memory 0.2.0__py3-none-any.whl

mnemon/__init__.py

@@ -0,0 +1,3 @@
+"""mnemon — Universal long-term memory layer for AI agents via MCP."""
+
+__version__ = "0.2.0"

mnemon/cli.py

@@ -0,0 +1,181 @@
+"""CLI entry point for mnemon.
+
+Usage:
+    mnemon serve              Start MCP server (stdio transport)
+    mnemon serve-remote       Start HTTP server (Streamable HTTP)
+    mnemon status             Show vault health stats
+    mnemon search <query>     Search memories
+    mnemon save <title> <content>  Save a memory
+    mnemon setup <target>     Configure integration (claude-code, cursor, gemini, hooks)
+    mnemon sync push          Push vault to S3
+    mnemon sync pull          Pull vault from S3
+    mnemon --version          Show version
+    mnemon --help             Show this help
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    command = args[0] if args else "--help"
+
+    if command in ("--version", "-v"):
+        print(f"mnemon v{__version__}")
+        return
+
+    if command in ("--help", "-h"):
+        _print_usage()
+        return
+
+    if command == "serve":
+        from .server import run_stdio
+        run_stdio()
+
+    elif command == "serve-remote":
+        from .server_remote import run_remote
+        run_remote()
+
+    elif command == "status":
+        from .store import Store
+        store = Store()
+        stats = store.status()
+        print(f"Vault: {stats['vault_path']}")
+        print(f"Total memories: {stats['total_documents']}")
+        print(f"Vectors: {stats['total_vectors']}")
+        print(f"Pinned: {stats['pinned']}")
+        print(f"Invalidated: {stats['invalidated']}")
+        print("\nBy type:")
+        for t in stats["by_type"]:
+            print(f"  {t['content_type']}: {t['count']}")
+        store.close()
+
+    elif command == "search":
+        query = " ".join(args[1:])
+        if not query:
+            print("Usage: mnemon search <query>", file=sys.stderr)
+            sys.exit(1)
+        from .search import search
+        from .store import Store
+        store = Store()
+        results = search(store, query, limit=10)
+        if not results:
+            print("No memories found.")
+        else:
+            for r in results:
+                snippet = r.content[:200]
+                ellipsis = "..." if len(r.content) > 200 else ""
+                print(f"[{r.content_type}] {r.title} (score: {r.composite_score:.3f})")
+                print(f"  {snippet}{ellipsis}")
+                print()
+        store.close()
+
+    elif command == "save":
+        if len(args) < 3:
+            print("Usage: mnemon save <title> <content>", file=sys.stderr)
+            sys.exit(1)
+        title = args[1]
+        content = " ".join(args[2:])
+        from .store import Store
+        store = Store()
+        doc_id = store.save(title=title, content=content, source_client="cli")
+        print(f'Saved memory #{doc_id}: "{title}"')
+        store.close()
+
+    elif command == "forget":
+        if len(args) < 2 or not args[1].isdigit():
+            print("Usage: mnemon forget <id>", file=sys.stderr)
+            sys.exit(1)
+        doc_id = int(args[1])
+        from .store import Store
+        store = Store()
+        if store.forget(doc_id):
+            print(f"Forgot memory #{doc_id}.")
+        else:
+            print(f"Memory #{doc_id} not found or already forgotten.", file=sys.stderr)
+            sys.exit(1)
+        store.close()
+
+    elif command == "sync":
+        subcommand = args[1] if len(args) > 1 else ""
+        if subcommand == "push":
+            from .sync import push
+            result = push()
+            if result["pushed"]:
+                print("Pushed:")
+                for p in result["pushed"]:
+                    print(f"  {p}")
+            if result["errors"]:
+                print("Errors:", file=sys.stderr)
+                for e in result["errors"]:
+                    print(f"  {e}", file=sys.stderr)
+                sys.exit(1)
+            if not result["pushed"] and not result["errors"]:
+                print("No vault files found to push.")
+        elif subcommand == "pull":
+            from .sync import pull
+            result = pull()
+            if result["pulled"]:
+                print("Pulled:")
+                for p in result["pulled"]:
+                    print(f"  {p}")
+            if result["errors"]:
+                print("Errors:", file=sys.stderr)
+                for e in result["errors"]:
+                    print(f"  {e}", file=sys.stderr)
+                sys.exit(1)
+            if not result["pulled"] and not result["errors"]:
+                print("No vault files found on S3.")
+        else:
+            print("Usage: mnemon sync <push|pull>", file=sys.stderr)
+            print("\nEnv vars:")
+            print("  MNEMON_S3_BUCKET   S3 bucket name (required)")
+            print("  MNEMON_S3_PREFIX   S3 key prefix (default: mnemon/vaults)")
+            print("  MNEMON_VAULT_NAME  vault name (default: default)")
+            sys.exit(1)
+
+    elif command == "setup":
+        target = args[1] if len(args) > 1 else ""
+        if not target:
+            print("Usage: mnemon setup <claude-code|cursor|gemini|hooks>", file=sys.stderr)
+            sys.exit(1)
+        from .setup import run_setup
+        print(run_setup(target))
+
+    else:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        _print_usage()
+        sys.exit(1)
+
+
+def _print_usage() -> None:
+    print(f"""mnemon v{__version__} — Universal long-term memory for AI agents
+
+Usage:
+  mnemon serve              Start MCP server (stdio transport)
+  mnemon serve-remote       Start HTTP server (Streamable HTTP)
+  mnemon status             Show vault health stats
+  mnemon search <query>     Search memories
+  mnemon save <title> <c>   Save a memory
+  mnemon forget <id>        Soft-delete a memory
+  mnemon setup <target>     Configure integration (claude-code, cursor, gemini, hooks)
+  mnemon sync push          Push vault to S3
+  mnemon sync pull          Pull vault from S3
+  mnemon --version          Show version
+  mnemon --help             Show this help
+
+Env vars:
+  MNEMON_VAULT_DIR    Vault directory (default: ~/.mnemon)
+  MNEMON_TOKEN        Bearer token for remote server auth
+  MNEMON_S3_BUCKET    S3 bucket for vault sync
+  PORT                Remote server port (default: 8502)
+
+Docs: https://github.com/cipher813/mnemon""")
+
+
+if __name__ == "__main__":
+    main()

mnemon/config.py

@@ -0,0 +1,79 @@
+"""Configuration — content types, vault paths, scoring constants."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import Path
+
+
+class ContentType(str, Enum):
+    DECISION = "decision"
+    PREFERENCE = "preference"
+    ANTIPATTERN = "antipattern"
+    OBSERVATION = "observation"
+    RESEARCH = "research"
+    PROJECT = "project"
+    HANDOFF = "handoff"
+    NOTE = "note"
+
+
+class MemoryType(str, Enum):
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+
+
+# Content type → memory type mapping
+MEMORY_TYPE_MAP: dict[ContentType, MemoryType] = {
+    ContentType.DECISION: MemoryType.SEMANTIC,
+    ContentType.PREFERENCE: MemoryType.SEMANTIC,
+    ContentType.ANTIPATTERN: MemoryType.SEMANTIC,
+    ContentType.OBSERVATION: MemoryType.SEMANTIC,
+    ContentType.RESEARCH: MemoryType.SEMANTIC,
+    ContentType.PROJECT: MemoryType.SEMANTIC,
+    ContentType.HANDOFF: MemoryType.EPISODIC,
+    ContentType.NOTE: MemoryType.SEMANTIC,
+}
+
+# Half-lives in days (None = never decay)
+HALF_LIVES: dict[ContentType, int | None] = {
+    ContentType.DECISION: None,
+    ContentType.PREFERENCE: None,
+    ContentType.ANTIPATTERN: None,
+    ContentType.OBSERVATION: 90,
+    ContentType.RESEARCH: 90,
+    ContentType.PROJECT: 120,
+    ContentType.HANDOFF: 30,
+    ContentType.NOTE: 60,
+}
+
+# Default confidence per content type
+DEFAULT_CONFIDENCE: dict[ContentType, float] = {
+    ContentType.DECISION: 0.85,
+    ContentType.PREFERENCE: 0.80,
+    ContentType.ANTIPATTERN: 0.80,
+    ContentType.OBSERVATION: 0.70,
+    ContentType.RESEARCH: 0.70,
+    ContentType.PROJECT: 0.65,
+    ContentType.HANDOFF: 0.60,
+    ContentType.NOTE: 0.50,
+}
+
+# Scoring constants
+RRF_K = 60
+MMR_THRESHOLD = 0.6
+COMPOSITE_WEIGHTS = (0.5, 0.25, 0.25)  # (relevance, recency, confidence)
+RECENCY_HALF_LIFE_DAYS = 30
+PIN_BOOST = 0.3
+
+# Content type enum values for validation
+CONTENT_TYPE_VALUES = [ct.value for ct in ContentType]
+
+
+def vault_dir() -> Path:
+    return Path(os.environ.get("MNEMON_VAULT_DIR", Path.home() / ".mnemon"))
+
+
+def vault_path() -> Path:
+    return vault_dir() / "default.sqlite"

mnemon/contradiction.py

@@ -0,0 +1,183 @@
+"""Contradiction detection — finds and resolves conflicting memories.
+
+When a new memory is saved, searches for existing memories on the same
+topic. Uses the local LLM to classify the relationship:
+  - same: identical fact, no action (adds "related" relation)
+  - update: new supersedes old, decay old confidence
+  - contradiction: direct conflict, decay old confidence more aggressively
+  - unrelated: different topics, no action
+
+Also provides time-based confidence decay with access reinforcement.
+
+Phase 3: LLM-based contradiction detection + confidence decay.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import SearchResult, Store
+
+OVERLAP_THRESHOLD = 0.7  # minimum vector similarity to consider overlapping
+UPDATE_DECAY = 0.15      # confidence reduction for superseded memories
+CONTRADICTION_DECAY = 0.25
+CONFIDENCE_FLOOR = 0.2
+
+CLASSIFY_SYSTEM_PROMPT = (
+    "You classify the relationship between two memories. "
+    "Given an existing memory and a new memory, respond with exactly one word:\n\n"
+    "- same: they express the same fact or decision\n"
+    "- update: the new memory supersedes or refines the old one\n"
+    "- contradiction: they directly conflict\n"
+    "- unrelated: different topics\n\n"
+    "Respond with ONLY the classification word, nothing else."
+)
+
+VALID_CLASSIFICATIONS = {"same", "update", "contradiction", "unrelated"}
+
+
+def check_contradictions(
+    store: "Store",
+    new_title: str,
+    new_content: str,
+    new_doc_id: int,
+) -> dict:
+    """Check a new memory against existing memories for contradictions.
+
+    Returns {decayed: int, relationships: [{doc_id, title, relationship}]}.
+    """
+    relationships: list[dict] = []
+    decayed = 0
+
+    # Find overlapping memories via vector similarity
+    try:
+        from .embedder import embed
+        query_emb = embed(f"title: {new_title} | text: {new_content}")
+        overlapping = store.search_vector(query_emb, 5)
+    except Exception:
+        return {"decayed": 0, "relationships": []}
+
+    # Filter to genuinely overlapping results (exclude self)
+    candidates = [
+        r for r in overlapping
+        if r.doc_id != new_doc_id and r.score >= OVERLAP_THRESHOLD
+    ]
+
+    if not candidates:
+        return {"decayed": 0, "relationships": []}
+
+    # Classify each relationship via LLM
+    try:
+        from .llm import generate
+    except ImportError:
+        return {"decayed": 0, "relationships": []}
+
+    for candidate in candidates:
+        try:
+            prompt = (
+                f"Existing memory:\nTitle: {candidate.title}\n"
+                f"Content: {candidate.content[:500]}\n\n"
+                f"New memory:\nTitle: {new_title}\n"
+                f"Content: {new_content[:500]}"
+            )
+
+            response = generate(CLASSIFY_SYSTEM_PROMPT, prompt, max_tokens=10)
+            classification = response.strip().lower()
+
+            if classification not in VALID_CLASSIFICATIONS:
+                continue
+
+            relationships.append({
+                "doc_id": candidate.doc_id,
+                "title": candidate.title,
+                "relationship": classification,
+            })
+
+            # Apply confidence decay
+            if classification == "update":
+                doc = store.get(candidate.doc_id)
+                if doc:
+                    new_confidence = max(CONFIDENCE_FLOOR, doc.confidence - UPDATE_DECAY)
+                    store.db.execute(
+                        "UPDATE documents SET confidence = ?, updated_at = datetime('now') WHERE id = ?",
+                        (new_confidence, candidate.doc_id),
+                    )
+                    store.db.commit()
+                    store.add_relation(new_doc_id, candidate.doc_id, "supersedes", 0.8)
+                    decayed += 1
+
+            elif classification == "contradiction":
+                doc = store.get(candidate.doc_id)
+                if doc:
+                    new_confidence = max(CONFIDENCE_FLOOR, doc.confidence - CONTRADICTION_DECAY)
+                    store.db.execute(
+                        "UPDATE documents SET confidence = ?, updated_at = datetime('now') WHERE id = ?",
+                        (new_confidence, candidate.doc_id),
+                    )
+                    store.db.commit()
+                    store.add_relation(new_doc_id, candidate.doc_id, "contradicts", 0.9)
+                    decayed += 1
+
+            elif classification == "same":
+                store.add_relation(new_doc_id, candidate.doc_id, "related", 1.0)
+
+        except Exception:
+            continue
+
+    return {"decayed": decayed, "relationships": relationships}
+
+
+# ── Confidence Decay ────────────────────────────────────────────────────────
+
+from .config import DEFAULT_CONFIDENCE, HALF_LIVES  # noqa: E402
+
+
+def apply_confidence_decay(store: "Store") -> int:
+    """Apply time-based confidence decay to all documents.
+
+    Documents with access activity decay slower (access reinforcement).
+    Each access extends the effective half-life by 10%, up to 3x.
+
+    Returns the number of documents whose confidence was updated.
+    """
+    updated = 0
+
+    for content_type, half_life in HALF_LIVES.items():
+        if half_life is None:
+            continue
+
+        rows = store.db.execute(
+            """SELECT id, confidence, access_count, pinned,
+                      CAST(julianday('now') - julianday(updated_at) AS REAL) AS age_days
+               FROM documents
+               WHERE content_type = ?
+                 AND invalidated_at IS NULL
+                 AND pinned = 0""",
+            (content_type.value,),
+        ).fetchall()
+
+        for row in rows:
+            # Access reinforcement: each access extends effective half-life
+            # More accesses = slower decay (up to 3x half-life extension)
+            access_multiplier = min(3.0, 1.0 + row["access_count"] * 0.1)
+            effective_half_life = half_life * access_multiplier
+
+            # Exponential decay: base_confidence * 2^(-age/halflife)
+            decay_factor = math.pow(2, -row["age_days"] / effective_half_life)
+            base_confidence = DEFAULT_CONFIDENCE.get(content_type, 0.5)
+            decayed_confidence = max(CONFIDENCE_FLOOR, base_confidence * decay_factor)
+
+            # Only update if confidence changed meaningfully
+            if abs(decayed_confidence - row["confidence"]) > 0.01:
+                store.db.execute(
+                    "UPDATE documents SET confidence = ? WHERE id = ?",
+                    (decayed_confidence, row["id"]),
+                )
+                updated += 1
+
+    if updated > 0:
+        store.db.commit()
+
+    return updated

mnemon/embedder.py

@@ -0,0 +1,84 @@
+"""Embedding pipeline — FastEmbed with bge-small-en-v1.5 (ONNX).
+
+384-dimensional embeddings via ONNX Runtime. ~13MB model, auto-downloaded.
+No PyTorch dependency needed.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+    from .store import Store
+
+VECTOR_DIM = 384
+_MODEL_NAME = "BAAI/bge-small-en-v1.5"
+
+_model = None
+
+
+def _get_model():
+    """Lazy-load the embedding model (singleton)."""
+    global _model
+    if _model is None:
+        from fastembed import TextEmbedding
+        _model = TextEmbedding(model_name=_MODEL_NAME)
+    return _model
+
+
+def embed(text: str) -> "np.ndarray":
+    """Embed a single text string. Returns ndarray of shape (384,)."""
+    import numpy as np
+    model = _get_model()
+    result = list(model.embed([text]))
+    return np.asarray(result[0], dtype=np.float32)
+
+
+def embed_batch(texts: list[str]) -> list["np.ndarray"]:
+    """Embed multiple texts."""
+    import numpy as np
+    model = _get_model()
+    results = list(model.embed(texts))
+    return [np.asarray(r, dtype=np.float32) for r in results]
+
+
+def fragmentize(title: str, content: str) -> list[dict]:
+    """Split a document into fragments for embedding.
+
+    Returns list of {seq, text} dicts:
+      seq=0: full document (title + content, truncated to 2000 chars)
+      seq=1-5: individual sections split by markdown headers or double newlines
+    """
+    fragments = []
+
+    # seq=0: full document
+    full_text = f"title: {title} | text: {content}"[:2000]
+    fragments.append({"seq": 0, "text": full_text})
+
+    # Split by markdown headers or double newlines
+    sections = re.split(r"(?=^#{1,3}\s)", content, flags=re.MULTILINE)
+    sections = [s.strip() for s in sections if len(s.strip()) > 50]
+
+    for i, section in enumerate(sections[:5]):
+        fragments.append({
+            "seq": i + 1,
+            "text": f"title: {title} | section: {section[:1000]}",
+        })
+
+    return fragments
+
+
+def embed_document(store: "Store", content_hash: str, title: str, content: str) -> int:
+    """Embed and store all fragments for a document. Returns fragment count."""
+    fragments = fragmentize(title, content)
+    count = 0
+
+    for frag in fragments:
+        emb = embed(frag["text"])
+        store.save_embedding(content_hash, frag["seq"], emb)
+        count += 1
+
+    store.flush_vectors()
+    return count

mnemon/hooks/context_surfacing.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Context surfacing hook — UserPromptSubmit.
+
+Searches the vault for relevant memories and injects them as
+XML context before Claude processes the prompt.
+
+Pipeline:
+  1. Skip noise (slash commands, greetings, short prompts, duplicates)
+  2. BM25 + vector search
+  3. Composite scoring (relevance + recency + confidence)
+  4. Tiered injection (HOT/WARM/COLD) within 800 token budget
+"""
+
+from __future__ import annotations
+
+import sys
+
+TOKEN_BUDGET = 800
+CHARS_PER_TOKEN = 4
+CHAR_BUDGET = TOKEN_BUDGET * CHARS_PER_TOKEN
+
+HOT_THRESHOLD = 0.15
+WARM_THRESHOLD = 0.10
+HOT_SNIPPET_LEN = 300
+WARM_SNIPPET_LEN = 150
+
+
+def build_context(results: list) -> str:
+    if not results:
+        return ""
+
+    lines: list[str] = []
+    chars_used = 0
+
+    for r in results:
+        if r.composite_score >= HOT_THRESHOLD:
+            snippet = r.content[:HOT_SNIPPET_LEN].replace("\n", " ")
+            ellipsis = "..." if len(r.content) > HOT_SNIPPET_LEN else ""
+            entry = f"[{r.content_type}] {r.title}: {snippet}{ellipsis}"
+        elif r.composite_score >= WARM_THRESHOLD:
+            snippet = r.content[:WARM_SNIPPET_LEN].replace("\n", " ")
+            entry = f"[{r.content_type}] {r.title}: {snippet}..."
+        else:
+            entry = f"[{r.content_type}] {r.title}"
+
+        if chars_used + len(entry) > CHAR_BUDGET:
+            break
+
+        lines.append(entry)
+        chars_used += len(entry)
+
+    if not lines:
+        return ""
+
+    return (
+        "<mnemon-context>\n"
+        "Relevant memories from previous sessions:\n"
+        + "\n".join(lines)
+        + "\n</mnemon-context>"
+    )
+
+
+def main() -> None:
+    try:
+        from .framework import read_stdin, write_output, is_noise, is_duplicate
+
+        hook_input = read_stdin()
+        prompt = hook_input.get("prompt", "")
+
+        if is_noise(prompt):
+            return
+        if is_duplicate(prompt):
+            return
+
+        from ..store import Store
+        from ..search import search
+
+        store = Store()
+        try:
+            results = search(store, prompt, limit=8, use_vector=True)
+            if not results:
+                return
+
+            context = build_context(results)
+            if not context:
+                return
+
+            write_output({
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": context,
+                },
+            })
+        finally:
+            store.close()
+    except Exception as e:
+        print(f"mnemon context-surfacing error: {e}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()