ace-mcp-server 0.3.0__py3-none-any.whl

ace_mcp/__init__.py

@@ -0,0 +1,18 @@
+"""
+Ace MCP Server
+
+Ace your AI memory. Free. Simple. Local.
+
+Exposes PVM persistent memory as MCP tools for any AI tool
+(Cursor, Claude Desktop, Windsurf, Codex, Copilot, etc.)
+
+Author:  Wenhui Tian (田文辉)
+Email:   rocky007cn@outlook.com
+GitHub:  https://github.com/rocky007cn/ace-memory
+License: BSL 1.1 → MIT 2030
+"""
+
+__version__ = "0.3.0"
+__author__ = "Wenhui Tian"
+__email__ = "rocky007cn@outlook.com"
+__url__ = "https://github.com/rocky007cn/ace-memory"

ace_mcp/ace_fuzzy.py

@@ -0,0 +1,315 @@
+"""
+Fuzzy Attribution — PVM Paper Chapter 6 Implementation
+
+Author:  Wenhui Tian (田文辉)
+Email:   rocky007cn@outlook.com
+GitHub:  https://github.com/rocky007cn/ace-memory
+
+When multiple candidates are comparably scored, PVM does not guess.
+Instead, it honestly reports the common features of all candidates,
+maintaining user trust while accumulating calibration signals.
+
+Trigger conditions (all three must be met):
+  1. Candidate count >= 2
+  2. Temporal span between candidates > threshold (default: 180 days)
+  3. Similarity score variance < threshold (default: 0.2)
+
+Reference: "Persistent Vector Memory" Section 6.2
+"""
+
+import re
+import time
+from collections import Counter
+from typing import Optional
+
+from pvm import PVMRecord
+from pvm.ranking import composite_score
+
+
+class FuzzyAttributor:
+    """Implements the full fuzzy attribution mechanism from PVM Chapter 6."""
+
+    def __init__(
+        self,
+        temporal_span_threshold: float = 180.0,
+        score_variance_threshold: float = 0.2,
+        min_candidates: int = 2,
+    ):
+        """
+        Args:
+            temporal_span_threshold: Min days between oldest and newest
+                candidate to trigger fuzzy mode. Paper default: 180 days.
+            score_variance_threshold: Max score gap between top and bottom
+                candidate. Paper default: 0.2.
+            min_candidates: Minimum candidates to trigger. Paper default: 2.
+        """
+        self.temporal_span_threshold = temporal_span_threshold
+        self.score_variance_threshold = score_variance_threshold
+        self.min_candidates = min_candidates
+
+    def analyze(
+        self,
+        candidates: list[PVMRecord],
+        lambda_decay: float = 0.01,
+    ) -> Optional[dict]:
+        """Analyze candidates and return fuzzy attribution if triggered.
+
+        This implements the full three-condition check from Section 6.2:
+        1. Enough candidates
+        2. Temporal span exceeds threshold
+        3. Score variance below threshold (no clear winner)
+
+        Args:
+            candidates: Ranked list of PVMRecord (already sorted by score).
+            lambda_decay: Temporal decay rate for score computation.
+
+        Returns:
+            None if attribution is clear-cut (single winner dominates).
+            Dict with fuzzy attribution info if triggered.
+        """
+        if len(candidates) < self.min_candidates:
+            return None
+
+        # --- Condition 1: Score variance ---
+        scores = [composite_score(c, lambda_decay) for c in candidates]
+        top_score = max(scores)
+        bottom_score = min(scores)
+        score_gap = top_score - bottom_score
+
+        if score_gap > self.score_variance_threshold:
+            return None  # Clear winner, no fuzzy needed
+
+        # --- Condition 2: Temporal span ---
+        timestamps = [c.last_activated for c in candidates if c.last_activated]
+        if not timestamps:
+            return None
+
+        earliest = min(timestamps)
+        latest = max(timestamps)
+        temporal_span_days = (latest - earliest) / 86400.0
+
+        if temporal_span_days < self.temporal_span_threshold:
+            # Temporal span too small — candidates are from the same period.
+            # Still return fuzzy info but mark it as "low_confidence".
+            # The paper's default is 180 days, but we don't want to hide
+            # ambiguous results just because they're recent.
+            pass
+
+        # --- Extract common features ---
+        common_features = self._extract_common_features(candidates)
+        category = self._classify_candidates(candidates)
+
+        # --- Build honest summary ---
+        summary = self._build_summary(
+            candidates, common_features, category,
+            temporal_span_days, score_gap,
+        )
+
+        triggered = (
+            temporal_span_days >= self.temporal_span_threshold
+            and score_gap <= self.score_variance_threshold
+        )
+
+        return {
+            "mode": "fuzzy_attribution",
+            "triggered": triggered,
+            "trigger_conditions": {
+                "candidate_count": len(candidates),
+                "candidate_count_met": len(candidates) >= self.min_candidates,
+                "temporal_span_days": round(temporal_span_days, 1),
+                "temporal_span_met": temporal_span_days >= self.temporal_span_threshold,
+                "score_gap": round(score_gap, 4),
+                "score_variance_met": score_gap <= self.score_variance_threshold,
+            },
+            "category": category,
+            "common_features": common_features,
+            "honest_summary": summary,
+            "candidates": [
+                {
+                    "fingerprint": c.fingerprint.hex(),
+                    "content_preview": c.content[:150],
+                    "weight": round(c.weight, 4),
+                    "score": round(composite_score(c, lambda_decay), 4),
+                    "created_at": c.created_at,
+                    "last_activated": c.last_activated,
+                }
+                for c in candidates
+            ],
+            "advice": (
+                "Multiple memories match this query with similar scores. "
+                "Do NOT pick one and present it as certain. Instead, "
+                "summarize the common pattern across these memories and "
+                "let the user confirm which one they mean. "
+                "If the user confirms, call ace_calibrate with signal=1.0 "
+                "for the correct memory to sharpen future retrieval."
+            ),
+        }
+
+    def _extract_common_features(
+        self, candidates: list[PVMRecord]
+    ) -> dict:
+        """Extract common features across candidates.
+
+        Goes beyond simple token intersection:
+        - Shared keywords (content tokens)
+        - Shared memory types
+        - Shared sources
+        - Shared tags
+        """
+        # Tokenize each candidate's content
+        token_lists = [self._tokenize(c.content) for c in candidates]
+        token_sets = [set(tl) for tl in token_lists]
+
+        # Intersection of all token sets
+        common_tokens = token_sets[0]
+        for ts in token_sets[1:]:
+            common_tokens = common_tokens & ts
+
+        # Remove stop words and noise
+        common_tokens = self._filter_stop_words(common_tokens)
+
+        # Frequency across candidates (how many candidates have this token)
+        token_frequency = Counter()
+        for tl in token_lists:
+            for t in set(tl):  # unique per candidate
+                token_frequency[t] += 1
+
+        # Sort by frequency (most common first)
+        common_sorted = sorted(
+            common_tokens,
+            key=lambda t: (-token_frequency[t], t),
+        )
+
+        # Extract memory types
+        types = set()
+        sources = set()
+        for c in candidates:
+            content = c.content
+            # Extract type: [source:X] [type] content
+            if "[source:" in content:
+                src_start = content.find("[source:") + 8
+                src_end = content.find("]", src_start)
+                if src_end > 0:
+                    sources.add(content[src_start:src_end])
+            # Extract type tag
+            type_match = re.search(r"\[(fact|preference|decision|correction|context)\]", content)
+            if type_match:
+                types.add(type_match.group(1))
+
+        return {
+            "shared_keywords": common_sorted[:20],
+            "shared_types": sorted(types) if types else [],
+            "shared_sources": sorted(sources) if sources else [],
+            "total_unique_keywords": len(common_tokens),
+        }
+
+    def _classify_candidates(
+        self, candidates: list[PVMRecord]
+    ) -> str:
+        """Classify what kind of ambiguity this is.
+
+        Returns one of:
+        - "temporal_ambiguity": same topic, different time periods
+        - "topic_overlap": different events with shared elements
+        - "correction_chain": original + corrected versions
+        - "general": generic ambiguity
+        """
+        # Check if any candidate is a correction of another
+        for c in candidates:
+            for e in c.edges:
+                if e.relation_type == "corrects":
+                    for other in candidates:
+                        if other.fingerprint == e.target_id:
+                            return "correction_chain"
+
+        # Check temporal spread
+        timestamps = [c.last_activated for c in candidates if c.last_activated]
+        if timestamps:
+            span = (max(timestamps) - min(timestamps)) / 86400.0
+            if span > 90:
+                return "temporal_ambiguity"
+
+        return "topic_overlap"
+
+    def _build_summary(
+        self,
+        candidates: list[PVMRecord],
+        features: dict,
+        category: str,
+        temporal_span: float,
+        score_gap: float,
+    ) -> str:
+        """Build an honest summary for the AI to use.
+
+        This is NOT the final user-facing text — the AI (LLM) should
+        use this as input to generate a natural response.
+        The summary provides the structured facts; the LLM provides
+        the language.
+        """
+        keywords = features.get("shared_keywords", [])
+        keyword_str = ", ".join(keywords[:10]) if keywords else "(none)"
+
+        parts = [
+            f"Fuzzy attribution triggered: {len(candidates)} candidates "
+            f"with score gap {score_gap:.4f} (threshold: {self.score_variance_threshold}).",
+            f"Temporal span: {temporal_span:.1f} days "
+            f"(threshold: {self.temporal_span_threshold} days).",
+            f"Category: {category}.",
+            f"Common keywords: {keyword_str}.",
+        ]
+
+        if category == "correction_chain":
+            parts.append(
+                "This includes an original memory and its correction. "
+                "Present both versions to the user."
+            )
+        elif category == "temporal_ambiguity":
+            parts.append(
+                "These memories span a long time period. The user may be "
+                "referring to any of them. Summarize the pattern rather "
+                "than picking one."
+            )
+        else:
+            parts.append(
+                "These memories share common features but may refer to "
+                "different events. Present the common theme and ask "
+                "the user to clarify."
+            )
+
+        return " ".join(parts)
+
+    @staticmethod
+    def _tokenize(text: str) -> list[str]:
+        """Simple tokenizer for feature extraction."""
+        tokens = re.findall(r"\w+", text.lower())
+        # Also extract CJK characters as individual tokens
+        cjk = re.findall(r"[\u4e00-\u9fff]+", text)
+        for segment in cjk:
+            # Simple bigram extraction for CJK
+            for i in range(len(segment) - 1):
+                tokens.append(segment[i:i+2])
+            tokens.append(segment)
+        return tokens
+
+    @staticmethod
+    def _filter_stop_words(tokens: set[str]) -> set[str]:
+        """Filter common stop words from token set."""
+        stop_words = {
+            "the", "a", "an", "is", "are", "was", "were", "be", "been",
+            "have", "has", "had", "do", "does", "did", "will", "would",
+            "could", "should", "may", "might", "must", "shall", "can",
+            "to", "of", "in", "for", "on", "with", "at", "by", "from",
+            "as", "into", "about", "like", "through", "after", "over",
+            "between", "out", "against", "during", "without", "before",
+            "under", "around", "among", "and", "but", "or", "not",
+            "no", "so", "if", "then", "that", "this", "these", "those",
+            "it", "i", "you", "he", "she", "we", "they", "me", "him",
+            "her", "us", "them", "my", "your", "his", "its", "our",
+            "their", "what", "which", "who", "when", "where", "why",
+            "how", "all", "each", "every", "both", "few", "more",
+            "most", "other", "some", "such", "only", "own", "same",
+            "than", "too", "very", "just", "also", "now", "here",
+            "there", "source", "fact", "preference", "decision",
+            "correction", "context", "reason",
+        }
+        return {t for t in tokens if t not in stop_words and len(t) > 1}

ace_mcp/server.py

@@ -0,0 +1,692 @@
+#!/usr/bin/env python3
+"""
+Ace MCP Server — Free AI Memory That Learns
+
+12 MCP tools that turn PVM into a complete memory layer for any AI tool.
+
+Author:  Wenhui Tian (田文辉)
+Email:   rocky007cn@outlook.com
+GitHub:  https://github.com/rocky007cn/ace-memory
+License: BSL 1.1 → MIT 2030
+
+Core (5 tools):
+  ace_save         — Store a memory
+  ace_search       — Search memories (keyword + semantic, fuzzy attribution)
+  ace_get_context  — Load recent memory context
+  ace_calibrate    — Feedback to evolve weights
+  ace_stats        — Engine statistics
+
+Differentiators (6 tools):
+  ace_correct      — Correct a memory WITHOUT losing the original (linked evolution)
+  ace_link         — Manually create relational edges between memories
+  ace_forget       — Soft-delete (weight → 0, preserved for audit)
+  ace_timeline     — Chronological memory view
+  ace_compare      — Compare original vs corrected versions (evolution chain)
+  ace_export       — Export all memories (json / text / summary)
+
+PVM Chapter 6 (1 tool):
+  ace_fuzzy_attribution — When uncertain, does NOT guess. Reports common features.
+
+Usage:
+  ace-mcp
+  ace-mcp --path ~/my-memory.jsonl
+  ace-mcp --no-embedding
+
+Config files in configs/ folder for Claude Desktop, Cursor, VS Code.
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import time
+from datetime import datetime
+from typing import Optional
+
+from pvm import PVMEngine, Edge, PVMRecord
+
+try:
+    from .ace_fuzzy import FuzzyAttributor
+except ImportError:
+    from ace_mcp.ace_fuzzy import FuzzyAttributor
+
+
+# ==============================================================================
+# Embedding — auto-upgrade: sentence-transformers if available, else hash
+# ==============================================================================
+
+# Try to load sentence-transformers (optional, zero-cost fallback)
+_ST_MODEL = None
+_ST_AVAILABLE = False
+try:
+    from sentence_transformers import SentenceTransformer
+    _ST_AVAILABLE = True
+except ImportError:
+    pass
+
+
+def _get_st_model():
+    """Lazily load the sentence-transformers model (only when first needed)."""
+    global _ST_MODEL
+    if _ST_MODEL is None and _ST_AVAILABLE:
+        _ST_MODEL = SentenceTransformer("all-MiniLM-L6-v2")
+    return _ST_MODEL
+
+
+def _embed(text: str) -> list[float]:
+    """Embed text. Uses sentence-transformers if available, else SHA-256 hash.
+
+    sentence-transformers gives true semantic search (database ≈ 数据库).
+    SHA-256 hash is deterministic, zero-dep, keyword-level matching.
+    """
+    if _ST_AVAILABLE:
+        model = _get_st_model()
+        vec = model.encode(text, normalize_embeddings=True)
+        return vec.tolist()
+    # Fallback: hash-based pseudo-embedding
+    dim = 64
+    h = hashlib.sha256(text.encode("utf-8")).digest()
+    vec = [(h[i % len(h)] + (i * 7 + 3) % 256) % 256 / 255.0 for i in range(dim)]
+    norm = sum(v * v for v in vec) ** 0.5
+    return [v / norm for v in vec] if norm > 0 else vec
+
+
+def _embedding_mode() -> str:
+    """Return current embedding mode for display."""
+    if _ST_AVAILABLE:
+        return "semantic (sentence-transformers/all-MiniLM-L6-v2)"
+    return "hash (SHA-256 pseudo-embedding)"
+
+
+# ==============================================================================
+# MCP SDK
+# ==============================================================================
+
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.server.models import InitializationOptions, ServerCapabilities
+    import mcp.types as types
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+
+
+# ==============================================================================
+# Global State
+# ==============================================================================
+
+_engine: Optional[PVMEngine] = None
+_embedding_dim: int = 64
+_use_embedding: bool = True
+_fuzzy: Optional[FuzzyAttributor] = None
+
+
+def get_engine() -> PVMEngine:
+    if _engine is None:
+        raise RuntimeError("Engine not initialized.")
+    return _engine
+
+
+def _fmt(rec: PVMRecord, full: bool = False) -> dict:
+    """Format a PVMRecord to JSON-safe dict."""
+    d = {
+        "fingerprint": rec.fingerprint.hex(),
+        "content": rec.content if full else rec.content[:500],
+        "weight": round(rec.weight, 4),
+        "created_at": rec.created_at,
+        "created_str": datetime.fromtimestamp(rec.created_at).isoformat()
+                       if rec.created_at else None,
+        "last_activated": rec.last_activated,
+        "edge_count": len(rec.edges),
+    }
+    if rec.edges:
+        d["edges"] = [{
+            "target": e.target_id.hex(),
+            "relation": e.relation_type,
+            "decay": e.activation_decay,
+        } for e in rec.edges]
+    return d
+
+
+# ==============================================================================
+# Tool 1: ace_save
+# ==============================================================================
+
+def tool_save(content: str, tags=None, weight: float = 0.5,
+              memory_type: str = "fact", source: str = "") -> dict:
+    """Store a memory. memory_type: fact|preference|decision|correction|context.
+    source: which AI tool created this (e.g. Cursor, Trae, Copilot)."""
+    eng = get_engine()
+    src_prefix = f"[source:{source}] " if source else ""
+    typed = f"{src_prefix}[{memory_type}] {content}"
+    emb = _embed(typed) if _use_embedding else None
+    all_tags = (tags or []) + [memory_type]
+    if source:
+        all_tags.append(source.lower())
+    fp = eng.store(content=typed, embedding=emb, weight=weight, keywords=all_tags)
+    return {"fingerprint": fp.hex(), "content": content[:200],
+            "type": memory_type, "source": source or "unknown",
+            "weight": weight, "stored": True}
+
+
+# ==============================================================================
+# Tool 2: ace_search
+# ==============================================================================
+
+def tool_search(query: str, keywords=None, top_k: int = 10,
+                include_full: bool = False) -> dict:
+    """Search memories. Dual-channel + full fuzzy attribution (Chapter 6)."""
+    eng = get_engine()
+    emb = _embed(query) if _use_embedding else None
+    results = eng.query(query_text=query, query_embedding=emb,
+                        keywords=keywords, top_k=top_k, propagate=True)
+    items = [_fmt(r, full=include_full) for r in results]
+
+    # Full fuzzy attribution per paper Chapter 6
+    fuzzy = None
+    if _fuzzy and len(results) >= 2:
+        fuzzy = _fuzzy.analyze(results, lambda_decay=eng.lambda_decay)
+
+    resp = {"query": query[:200], "total_found": len(items), "results": items}
+    if fuzzy:
+        resp["fuzzy_attribution"] = fuzzy
+    return resp
+
+
+# ==============================================================================
+# Tool 3: ace_get_context
+# ==============================================================================
+
+def tool_get_context(limit: int = 20, memory_type: str = None) -> dict:
+    """Recent memories, optionally filtered by type."""
+    eng = get_engine()
+    all_recs = sorted(eng.records.values(), key=lambda r: r.last_activated, reverse=True)
+    items = []
+    for r in all_recs:
+        if memory_type and not r.content.startswith(f"[{memory_type}]"):
+            continue
+        items.append(_fmt(r, full=True))
+        if len(items) >= limit:
+            break
+    return {"total_memories": len(eng), "returned": len(items), "memories": items}
+
+
+# ==============================================================================
+# Tool 4: ace_calibrate
+# ==============================================================================
+
+def tool_calibrate(fingerprint: str, signal: float, reason: str = "") -> dict:
+    """Evolve weight via Delta Rule. signal: 1=good, 0=bad, 0.5=neutral."""
+    eng = get_engine()
+    try:
+        fp = bytes.fromhex(fingerprint)
+    except ValueError:
+        return {"error": f"Invalid fingerprint: {fingerprint}"}
+    try:
+        eng.calibrate(fp, signal)
+    except KeyError:
+        return {"error": f"Memory not found: {fingerprint}"}
+    rec = eng.get(fp)
+    return {"fingerprint": fingerprint, "new_weight": round(rec.weight, 4),
+            "signal": signal, "reason": reason}
+
+
+# ==============================================================================
+# Tool 5: ace_correct  ★ THE KILLER FEATURE ★
+# ==============================================================================
+
+def tool_correct(original_fingerprint: str, corrected_content: str,
+                 reason: str = "", tags=None) -> dict:
+    """Correct a memory. Original kept (weight→0.2), new version stored
+    (weight→0.7) with 'corrects' edge. AI sees full evolution."""
+    eng = get_engine()
+    try:
+        fp_old = bytes.fromhex(original_fingerprint)
+    except ValueError:
+        return {"error": f"Invalid fingerprint: {original_fingerprint}"}
+
+    old_rec = eng.get(fp_old)
+    if old_rec is None:
+        return {"error": f"Original not found: {original_fingerprint}"}
+
+    # Preserve source from original if present
+    src = "unknown"
+    old_content = old_rec.content
+    if old_content.startswith("[source:"):
+        end = old_content.find("]", 8)
+        if end > 0:
+            src = old_content[8:end]
+
+    full = f"[source:{src}] [correction] {corrected_content}"
+    if reason:
+        full += f" | reason: {reason}"
+
+    emb = _embed(full) if _use_embedding else None
+    all_tags = (tags or []) + ["correction", "corrected"]
+    fp_new = eng.store(
+        content=full, embedding=emb, weight=0.7, keywords=all_tags,
+        edges=[Edge(target_id=fp_old, relation_type="corrects", activation_decay=0.5)],
+    )
+
+    eng.calibrate(fp_old, signal=0.2)
+    old_updated = eng.get(fp_old)
+
+    return {
+        "original": {"fingerprint": original_fingerprint,
+                     "content": old_rec.content[:200],
+                     "new_weight": round(old_updated.weight, 4)},
+        "corrected": {"fingerprint": fp_new.hex(),
+                      "content": full[:200], "weight": 0.7},
+        "reason": reason,
+        "evolution": f"{old_rec.content[:80]}... → {corrected_content[:80]}...",
+    }
+
+
+# ==============================================================================
+# Tool 6: ace_link
+# ==============================================================================
+
+def tool_link(src_fp: str, tgt_fp: str, relation: str = "related_to",
+              decay: float = 0.7) -> dict:
+    """Create edge between two memories. Relations: related_to|depends_on|
+    follows|contradicts|extends."""
+    eng = get_engine()
+    try:
+        src, tgt = bytes.fromhex(src_fp), bytes.fromhex(tgt_fp)
+    except ValueError:
+        return {"error": "Invalid fingerprint"}
+
+    src_rec, tgt_rec = eng.get(src), eng.get(tgt)
+    if not src_rec: return {"error": f"Source not found: {src_fp}"}
+    if not tgt_rec: return {"error": f"Target not found: {tgt_fp}"}
+
+    src_rec.edges.append(Edge(target_id=tgt, relation_type=relation,
+                              activation_decay=decay))
+    eng._sync_to_disk(src_rec)
+    return {"source": src_fp, "target": tgt_fp, "relation": relation, "linked": True}
+
+
+# ==============================================================================
+# Tool 7: ace_forget
+# ==============================================================================
+
+def tool_forget(fingerprint: str, reason: str = "") -> dict:
+    """Soft-delete. Weight → 0.001. Stays in storage, hidden from normal search."""
+    eng = get_engine()
+    try:
+        fp = bytes.fromhex(fingerprint)
+    except ValueError:
+        return {"error": f"Invalid fingerprint: {fingerprint}"}
+
+    rec = eng.get(fp)
+    if not rec: return {"error": f"Not found: {fingerprint}"}
+
+    old_w, content = rec.weight, rec.content[:200]
+    rec.weight = 0.001
+    rec.last_activated = time.time()
+    eng._sync_to_disk(rec)
+    return {"fingerprint": fingerprint, "content": content,
+            "old_weight": round(old_w, 4), "new_weight": 0.001,
+            "forgotten": True, "reason": reason}
+
+
+# ==============================================================================
+# Tool 8: ace_timeline
+# ==============================================================================
+
+def tool_timeline(start_time: float = None, end_time: float = None,
+                  memory_type: str = None, limit: int = 50) -> dict:
+    """Chronological memory view."""
+    eng = get_engine()
+    now = time.time()
+    t0, t1 = start_time or 0.0, end_time or now
+
+    filtered = [r for r in eng.records.values()
+                if t0 <= r.created_at <= t1
+                and (not memory_type or r.content.startswith(f"[{memory_type}]"))]
+    filtered.sort(key=lambda r: r.created_at)
+
+    items = []
+    for r in filtered[:limit]:
+        d = _fmt(r, full=True)
+        d["created_str"] = datetime.fromtimestamp(r.created_at).strftime("%Y-%m-%d %H:%M:%S")
+        items.append(d)
+
+    return {"time_range": {"start": t0, "end": t1},
+            "total_in_range": len(filtered), "returned": len(items),
+            "timeline": items}
+
+
+# ==============================================================================
+# Tool 9: ace_compare
+# ==============================================================================
+
+def tool_compare(fingerprint: str) -> dict:
+    """Show evolution chain: original → corrections → current."""
+    eng = get_engine()
+    try:
+        fp = bytes.fromhex(fingerprint)
+    except ValueError:
+        return {"error": f"Invalid fingerprint: {fingerprint}"}
+
+    rec = eng.get(fp)
+    if not rec: return {"error": f"Not found: {fingerprint}"}
+
+    chain = {
+        "this": _fmt(rec, full=True),
+        "corrects": [],
+        "corrected_by": [],
+    }
+
+    # Outgoing "corrects" edges
+    for e in rec.edges:
+        if e.relation_type == "corrects":
+            t = eng.get(e.target_id)
+            if t: chain["corrects"].append(_fmt(t, full=True))
+
+    # Incoming "corrects" edges
+    for _, other in eng.records.items():
+        for e in other.edges:
+            if e.target_id == fp and e.relation_type == "corrects":
+                chain["corrected_by"].append(_fmt(other, full=True))
+
+    vcount = 1 + len(chain["corrects"]) + len(chain["corrected_by"])
+    chain["evolution_summary"] = {"versions": vcount}
+    return chain
+
+
+# ==============================================================================
+# Tool 10: ace_export
+# ==============================================================================
+
+def tool_export(fmt: str = "json") -> dict:
+    """Export memories. fmt: json|text|summary."""
+    eng = get_engine()
+
+    if fmt == "summary":
+        types_cnt = {}
+        top = []
+        for r in sorted(eng.records.values(), key=lambda r: r.weight, reverse=True):
+            mt = "unknown"
+            if r.content.startswith("["):
+                end = r.content.find("]")
+                if end > 0: mt = r.content[1:end]
+            types_cnt[mt] = types_cnt.get(mt, 0) + 1
+            if len(top) < 10:
+                top.append({"fingerprint": r.fingerprint.hex(), "type": mt,
+                            "weight": round(r.weight, 4), "content": r.content[:120]})
+        return {"format": "summary", "total": len(eng), "by_type": types_cnt,
+                "top_weighted": top, "stats": eng.stats()}
+
+    if fmt == "text":
+        lines = [f"Ace Memory Export — {datetime.now():%Y-%m-%d %H:%M}",
+                 f"Total: {len(eng)} records\n"]
+        for r in sorted(eng.records.values(), key=lambda r: r.created_at):
+            ts = datetime.fromtimestamp(r.created_at).strftime("%Y-%m-%d %H:%M")
+            lines.append(f"[{ts}] (w={r.weight:.3f}) {r.content}")
+            for e in r.edges:
+                t = eng.get(e.target_id)
+                lines.append(f"    └─ {e.relation_type} → {t.content[:60] if t else '(missing)'}")
+            lines.append("")
+        return {"format": "text", "export": "\n".join(lines)}
+
+    return {"format": "json", "total": len(eng),
+            "memories": [_fmt(r, full=True) for r in eng.records.values()]}
+
+
+# ==============================================================================
+# Tool 11: ace_stats
+# ==============================================================================
+
+def tool_stats() -> dict:
+    s = get_engine().stats()
+    s["embedding_mode"] = _embedding_mode()
+    s["tool_count"] = 12
+    return s
+
+
+# ==============================================================================
+# Tool 12: ace_fuzzy_attribution  ★ PVM Chapter 6 ★
+# ==============================================================================
+
+def tool_fuzzy_attribution(query: str, top_k: int = 10) -> dict:
+    """Analyze a query for fuzzy attribution (PVM Chapter 6).
+
+    When multiple memories match with similar scores, PVM does NOT guess.
+    Instead, it reports common features across all candidates and advises
+    the AI to summarize rather than pick one.
+
+    This implements the full three-condition trigger:
+    1. Candidate count >= 2
+    2. Temporal span > 180 days (configurable)
+    3. Score variance < 0.2 (no clear winner)
+    """
+    eng = get_engine()
+    emb = _embed(query) if _use_embedding else None
+    results = eng.query(query_text=query, query_embedding=emb,
+                        top_k=top_k, propagate=True)
+
+    if not results:
+        return {"mode": "no_results", "query": query[:200]}
+
+    if len(results) == 1:
+        return {"mode": "clear_winner", "query": query[:200],
+                "result": _fmt(results[0], full=True)}
+
+    if not _fuzzy:
+        return {"mode": "disabled", "query": query[:200],
+                "results": [_fmt(r) for r in results]}
+
+    analysis = _fuzzy.analyze(results, lambda_decay=eng.lambda_decay)
+    if analysis is None:
+        return {"mode": "clear_winner", "query": query[:200],
+                "result": _fmt(results[0], full=True)}
+
+    return analysis
+
+
+# ==============================================================================
+# MCP Server
+# ==============================================================================
+
+def build_mcp_server() -> Server:
+    server = Server("ace-mcp")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(name="ace_save", description=(
+                "Store a memory. Full text, never chunked, never compressed. "
+                "memory_type: fact|preference|decision|correction|context. "
+                "source: which AI tool created this (e.g. Cursor, Trae, Copilot)."),
+                inputSchema={"type": "object", "properties": {
+                    "content": {"type": "string", "description": "Full text to remember."},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "weight": {"type": "number", "description": "Initial weight [0,1]."},
+                    "memory_type": {"type": "string", "enum": ["fact","preference","decision","correction","context"]},
+                    "source": {"type": "string", "description": "Which AI tool created this memory."},
+                }, "required": ["content"]}),
+
+            types.Tool(name="ace_search", description=(
+                "Search memories — deterministic keyword matching, no guessing. "
+                "When top results score similarly, returns fuzzy_attribution."),
+                inputSchema={"type": "object", "properties": {
+                    "query": {"type": "string", "description": "What to search for."},
+                    "keywords": {"type": "array", "items": {"type": "string"}},
+                    "top_k": {"type": "integer", "description": "Max results. Default 10."},
+                    "include_full": {"type": "boolean", "description": "Return full content."},
+                }, "required": ["query"]}),
+
+            types.Tool(name="ace_get_context", description=(
+                "Load recent memory context. Call at the START of every conversation."),
+                inputSchema={"type": "object", "properties": {
+                    "limit": {"type": "integer", "description": "Max memories. Default 20."},
+                    "memory_type": {"type": "string", "description": "Filter by type."},
+                }}),
+
+            types.Tool(name="ace_calibrate", description=(
+                "Evolve memory weight. signal 1.0=great, 0.0=bad, 0.5=neutral."),
+                inputSchema={"type": "object", "properties": {
+                    "fingerprint": {"type": "string", "description": "Hex fingerprint."},
+                    "signal": {"type": "number", "description": "Feedback [0,1]."},
+                    "reason": {"type": "string", "description": "Why this feedback."},
+                }, "required": ["fingerprint","signal"]}),
+
+            types.Tool(name="ace_correct", description=(
+                "★ Correct a memory WITHOUT losing the original. "
+                "Original weight → 0.2, new version weight → 0.7 with 'corrects' edge. "
+                "AI sees full evolution: what was said → what was corrected → why."),
+                inputSchema={"type": "object", "properties": {
+                    "original_fingerprint": {"type": "string", "description": "Fingerprint to correct."},
+                    "corrected_content": {"type": "string", "description": "Corrected information."},
+                    "reason": {"type": "string", "description": "Why the correction."},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                }, "required": ["original_fingerprint","corrected_content"]}),
+
+            types.Tool(name="ace_link", description=(
+                "Create relationship edge: related_to|depends_on|follows|contradicts|extends."),
+                inputSchema={"type": "object", "properties": {
+                    "source_fingerprint": {"type": "string"},
+                    "target_fingerprint": {"type": "string"},
+                    "relation": {"type": "string", "enum": ["related_to","depends_on","follows","contradicts","extends"]},
+                    "decay": {"type": "number", "description": "Activation decay [0,1]."},
+                }, "required": ["source_fingerprint","target_fingerprint","relation"]}),
+
+            types.Tool(name="ace_forget", description=(
+                "Soft-delete. Weight → 0.001. Preserved for audit, hidden from search."),
+                inputSchema={"type": "object", "properties": {
+                    "fingerprint": {"type": "string"},
+                    "reason": {"type": "string"},
+                }, "required": ["fingerprint"]}),
+
+            types.Tool(name="ace_timeline", description=(
+                "Chronological memory view with time range filter."),
+                inputSchema={"type": "object", "properties": {
+                    "start_time": {"type": "number", "description": "Unix timestamp."},
+                    "end_time": {"type": "number", "description": "Unix timestamp."},
+                    "memory_type": {"type": "string"},
+                    "limit": {"type": "integer", "description": "Default 50."},
+                }}),
+
+            types.Tool(name="ace_compare", description=(
+                "Show evolution chain of a memory: original → all corrections → current."),
+                inputSchema={"type": "object", "properties": {
+                    "fingerprint": {"type": "string"},
+                }, "required": ["fingerprint"]}),
+
+            types.Tool(name="ace_export", description=(
+                "Export all memories. Format: json|text|summary."),
+                inputSchema={"type": "object", "properties": {
+                    "format": {"type": "string", "enum": ["json","text","summary"]},
+                }}),
+
+            types.Tool(name="ace_stats", description="Engine statistics.",
+                inputSchema={"type": "object", "properties": {}}),
+
+            types.Tool(name="ace_fuzzy_attribution", description=(
+                "★ PVM Chapter 6: Fuzzy Attribution. "
+                "When multiple memories match with similar scores, does NOT guess. "
+                "Instead, reports common features and advises honest summarization. "
+                "Call this when ace_search returns multiple similar-scoring results."),
+                inputSchema={"type": "object", "properties": {
+                    "query": {"type": "string", "description": "What to search for."},
+                    "top_k": {"type": "integer", "description": "Max candidates. Default 10."},
+                }, "required": ["query"]}),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, args: dict) -> list[types.TextContent]:
+        dispatch = {
+            "ace_save": lambda: tool_save(args["content"], args.get("tags"),
+                                          args.get("weight", 0.5), args.get("memory_type", "fact"),
+                                          args.get("source", "")),
+            "ace_search": lambda: tool_search(args["query"], args.get("keywords"),
+                                              args.get("top_k", 10), args.get("include_full", False)),
+            "ace_get_context": lambda: tool_get_context(args.get("limit", 20), args.get("memory_type")),
+            "ace_calibrate": lambda: tool_calibrate(args["fingerprint"], args["signal"], args.get("reason", "")),
+            "ace_correct": lambda: tool_correct(args["original_fingerprint"], args["corrected_content"],
+                                                args.get("reason", ""), args.get("tags")),
+            "ace_link": lambda: tool_link(args["source_fingerprint"], args["target_fingerprint"],
+                                          args.get("relation", "related_to"), args.get("decay", 0.7)),
+            "ace_forget": lambda: tool_forget(args["fingerprint"], args.get("reason", "")),
+            "ace_timeline": lambda: tool_timeline(args.get("start_time"), args.get("end_time"),
+                                                  args.get("memory_type"), args.get("limit", 50)),
+            "ace_compare": lambda: tool_compare(args["fingerprint"]),
+            "ace_export": lambda: tool_export(args.get("format", "json")),
+            "ace_stats": lambda: tool_stats(),
+            "ace_fuzzy_attribution": lambda: tool_fuzzy_attribution(args["query"], args.get("top_k", 10)),
+        }
+        try:
+            fn = dispatch.get(name)
+            if fn is None:
+                result = {"error": f"Unknown tool: {name}"}
+            else:
+                result = fn()
+        except Exception as e:
+            result = {"error": str(e), "tool": name}
+
+        return [types.TextContent(type="text",
+                text=json.dumps(result, ensure_ascii=False, indent=2))]
+
+    return server
+
+
+# ==============================================================================
+# CLI
+# ==============================================================================
+
+def main():
+    global _engine, _embedding_dim, _use_embedding, _fuzzy
+
+    parser = argparse.ArgumentParser(description="Ace MCP Server — 12 tools")
+    parser.add_argument("--path", default=None,
+                        help="Storage path (default: ~/.ace/memory.jsonl)")
+    parser.add_argument("--no-embedding", action="store_true",
+                        help="Keyword-only mode")
+    parser.add_argument("--alpha", type=float, default=0.05,
+                        help="Learning rate (default: 0.05)")
+    args = parser.parse_args()
+
+    if args.path:
+        storage_path = os.path.expanduser(args.path)
+    else:
+        ace_dir = os.path.join(os.path.expanduser("~"), ".ace")
+        os.makedirs(ace_dir, exist_ok=True)
+        storage_path = os.path.join(ace_dir, "memory.jsonl")
+
+    _engine = PVMEngine(storage_path=storage_path, alpha=args.alpha,
+                        lambda_decay=0.01, similarity_threshold=0.3)
+    _use_embedding = not args.no_embedding
+    _embedding_dim = int(os.environ.get("ACE_EMBEDDING_DIM", "64"))
+    _fuzzy = FuzzyAttributor(
+        temporal_span_threshold=180.0,
+        score_variance_threshold=0.2,
+        min_candidates=2,
+    )
+
+    if not MCP_AVAILABLE:
+        print(f"♠ Ace MCP Server v{__import__('ace_mcp').__version__} — 12 tools ready")
+        print(f"   GitHub: https://github.com/rocky007cn/ace-memory")
+        print(f"   Author: Wenhui Tian — rocky007cn@outlook.com")
+        print(f"   Install: pip install mcp")
+        print(f"   Storage: {storage_path} | Records: {len(_engine)}")
+        print(f"   Embedding: {_embedding_mode()}")
+        if not _ST_AVAILABLE:
+            print(f"   Upgrade: pip install sentence-transformers (for semantic search)")
+        sys.exit(1)
+
+    import asyncio
+    server = build_mcp_server()
+
+    async def run():
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(read_stream, write_stream,
+                             InitializationOptions(server_name="ace-mcp", server_version="0.1.0", capabilities=ServerCapabilities()))
+
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

ace_mcp_server-0.3.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: ace-mcp-server
+Version: 0.3.0
+Summary: Ace MCP Server — Free AI memory that learns. Zero cloud, zero API keys, zero cost.
+Author-email: Wenhui Tian <rocky007cn@outlook.com>
+License: BSL-1.1
+Project-URL: Homepage, https://github.com/rocky007cn/ace-memory
+Project-URL: Repository, https://github.com/rocky007cn/ace-memory
+Keywords: mcp,mcp-server,ai-memory,memory,llm,agent-memory,rag,long-term-memory,local-first,free,zero-cost
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pvm-memory>=1.1.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
+
+# Ace MCP Server
+
+♠ **Ace your AI memory. Free. Simple. Local.**
+
+Zero-cost MCP server that gives any AI tool persistent, self-improving memory.
+
+## Install
+
+```bash
+pip install ace-mcp
+```
+
+Requires `pvm-memory` (installed automatically as dependency).
+
+## Quick Start
+
+### VS Code / Cursor
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "ace": {
+      "command": "python",
+      "args": ["-m", "ace_mcp.server"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ace": {
+      "command": "python",
+      "args": ["-m", "ace_mcp.server"]
+    }
+  }
+}
+```
+
+### Any MCP-compatible tool
+
+```bash
+ace-mcp                     # default: ~/.ace/memory.jsonl
+ace-mcp --path ./my-mem.jsonl
+ace-mcp --no-embedding      # keyword-only, faster
+```
+
+## Tools
+
+| Tool | What |
+|------|------|
+| `ace_save` | Store a memory |
+| `ace_search` | Keyword + semantic search |
+| `ace_get_context` | Recent memory context |
+| `ace_calibrate` | 👍/👎 feedback to train weights |
+| `ace_stats` | Engine statistics |
+
+## vs Mem0
+
+| | Mem0 | Ace |
+|---|---|---|
+| Price | 💰 Paid | 🆓 Free |
+| API Key | Required | None |
+| Cloud | Required | 100% Local |
+| GPU | Recommended | Not needed |
+| Dependencies | 50+ | 2 |
+| Information | Chunked/lossy | Full text |
+
+## License
+
+BSL 1.1 → MIT (2030)

ace_mcp_server-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ace_mcp/__init__.py,sha256=YVYdn0shm-ln_oRdZ2xz_1Zb2aB1aUA4JM8i4GB4znk,486
+ace_mcp/ace_fuzzy.py,sha256=4MGllNk7KnJbpL0twflug49Lpzy_XzQO-77PM7R-FCc,12237
+ace_mcp/server.py,sha256=m5D9a8WOS_If1WFEjX6w5g6GDr59U-fiLHnQrLbgs6M,29824
+ace_mcp_server-0.3.0.dist-info/METADATA,sha256=-IMHMadZYIz-KhO0x2OM2IPqbMvZhSOoqJrNfZ5yH3Y,2532
+ace_mcp_server-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ace_mcp_server-0.3.0.dist-info/entry_points.txt,sha256=VrF2-CeoDGzdqhLHgoETGZw9uBC3bIxCV_3by495f7Q,48
+ace_mcp_server-0.3.0.dist-info/top_level.txt,sha256=2p7I_QoPGw0wptjFbR6NoDSyrCVG9bDzueE6SK1CVDA,8
+ace_mcp_server-0.3.0.dist-info/RECORD,,

ace_mcp_server-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ace_mcp_server-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ace-mcp = ace_mcp.server:main

ace_mcp_server-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ace_mcp