ace-mcp-server 0.3.0__tar.gz

ace_mcp_server-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/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_server-0.3.0/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}