mnemo-agent 0.2.2__tar.gz → 0.3.1__tar.gz

{mnemo_agent-0.2.2 → mnemo_agent-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnemo-agent
-Version: 0.2.2
+Version: 0.3.1
 Summary: Local-first agent memory CLI — dump, diff, migrate & query across Mem0, Letta, and more
 Author: Joshua Ndala
 License-Expression: MIT
@@ -62,7 +62,7 @@ Inspired by Mnemosyne (Greek goddess of memory), **mnemo** is a portable CLI for
 - **TF-IDF search** — `mnemo recall "query"` with zero external ML deps, filterable by `--tag`
 - **Rich tables** — confidence color-coded (🟢 ≥0.8, 🟡 ≥0.5, 🔴 <0.5)
 - **HTML + graph diffs** — visual diff between dump snapshots
-- **MCP server** — FastAPI `/mcp/list_tools` + `/mcp/call_tool` for Ollama/Claude Code agents
+- **MCP server** — JSON-RPC 2.0 + stdio transport; plug directly into Claude Desktop, Cursor, or any MCP client
 - **Push/pull sync** — S3, Cloudflare R2, or local filesystem remote; timestamp-based merge
 - **Safe writes** — `--dry-run` on load, pull, and migrate
 
@@ -110,8 +110,10 @@ mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
 mnemo diff --agent-a job-prep --agent-b job-prep-v2
 mnemo diff dump1.json dump2.json --html diff_report.html
 
-# Start the MCP server (for Ollama / Claude Code agents)
+# Start the MCP server — HTTP mode
 mnemo serve --agent job-prep --port 8080
+# Or stdio mode (Claude Desktop / Cursor — no port needed)
+mnemo serve --agent job-prep --stdio
 
 # Sync to S3 (prompts for credentials on first add)
 mnemo remote add origin s3://my-bucket/mnemo --agent job-prep
@@ -137,7 +139,7 @@ mnemo pull --agent job-prep   # merges remote facts into local
 | `mnemo retract <fact-id> --agent <name>` | Remove a fact by ID or 8-char prefix |
 | `mnemo edit <fact-id> --agent <name>` | Edit value/attribute/confidence of an existing fact |
 | `mnemo migrate --dump f.json --target mem0 --agent name` | Migrate between providers |
-| `mnemo serve --agent <name> [--port 8080] [--read-only]` | MCP FastAPI server |
+| `mnemo serve --agent <name> [--port 8080] [--stdio] [--read-only]` | MCP server — HTTP (JSON-RPC 2.0) or stdio for Claude Desktop / Cursor |
 | `mnemo remote add <name> <url> --agent <name>` | Add a named remote (s3://, r2://, file://) |
 | `mnemo remote list --agent <name>` | List configured remotes |
 | `mnemo remote remove <name> --agent <name>` | Remove a remote |
@@ -157,13 +159,15 @@ mnemo-agent/
 │   ├── storage.py           # Local file I/O (JSON, YAML, credentials)
 │   ├── search.py            # TF-IDF search + diff engine
 │   ├── remotes.py           # Push/pull backends: FileBackend, S3Backend
-│   ├── server.py            # FastAPI MCP server
+│   ├── server.py            # FastAPI MCP server (HTTP + JSON-RPC 2.0)
+│   ├── stdio_server.py      # stdio MCP transport (Claude Desktop / Cursor)
 │   └── adapters/
 │       ├── mem0_adapter.py  # Mem0 API → normalized facts
 │       └── letta_adapter.py # Letta API → normalized facts
 ├── tests/
 │   ├── test_cli.py          # CLI command tests
 │   ├── test_remote.py       # Remote backends, merge, push/pull tests
+│   ├── test_server.py       # MCP server: JSON-RPC 2.0, tools, stdio transport
 │   └── fixtures/
 │       └── job_prep_sample.json
 ├── config.yaml              # Sample agent config
@@ -238,7 +242,28 @@ mnemo-agent/
 
 ---
 
-## 🔌 MCP Server (for Ollama / Claude Code)
+## 🔌 MCP Server
+
+mnemo implements the [MCP 2024-11-05 spec](https://spec.modelcontextprotocol.io) and supports two transports.
+
+### stdio — Claude Desktop / Cursor
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mnemo-job-prep": {
+      "command": "mnemo",
+      "args": ["serve", "--agent", "job-prep", "--stdio"]
+    }
+  }
+}
+```
+
+That's it — Claude Desktop will spawn mnemo as a subprocess and communicate over stdin/stdout.
+
+### HTTP — REST + JSON-RPC 2.0
 
 ```bash
 mnemo serve --agent job-prep --port 8080
@@ -246,20 +271,26 @@ mnemo serve --agent job-prep --port 8080
 
 | Endpoint | Description |
 |---|---|
-| `GET /mcp/list_tools` | List available tools (MCP schema) |
-| `POST /mcp/call_tool` | Call a tool by name with arguments |
-| `GET /facts` | REST: list all facts |
-| `GET /search?q=query` | REST: search memories |
+| `POST /` | JSON-RPC 2.0 — `initialize`, `tools/list`, `tools/call`, `ping` |
+| `GET /mcp/list_tools` | List available tools (legacy, kept for compatibility) |
+| `POST /mcp/call_tool` | Call a tool by name (legacy, kept for compatibility) |
+| `GET /facts` | REST: list all facts (`?entity=`, `?attribute=`, `?tag=`) |
+| `GET /search?q=query` | REST: search memories (`?tag=` filter supported) |
+| `GET /health` | Health check with version info |
 | `GET /docs` | Swagger UI |
 
 ### Available MCP tools
 
-```json
-{ "name": "search_memory",  "description": "TF-IDF search over agent memory" }
-{ "name": "list_facts",     "description": "Return all facts, optionally filtered" }
-{ "name": "upsert_fact",    "description": "Add a fact to agent memory" }
-{ "name": "get_agent_info", "description": "Agent metadata and fact count" }
-```
+| Tool | Description |
+|---|---|
+| `search_memory` | TF-IDF keyword search; supports `tag` filter |
+| `list_facts` | List all facts; filterable by `entity`, `attribute`, `tag`; shows IDs |
+| `upsert_fact` | Add a fact; supports `tags` array |
+| `retract_fact` | Remove a fact by ID or 8-char prefix |
+| `edit_fact` | Update a fact's `value`, `attribute`, or `confidence` |
+| `get_agent_info` | Agent name, fact count, last updated timestamp |
+
+`retract_fact` and `edit_fact` are disabled when `--read-only` is set.
 
 ---
 
@@ -299,20 +330,23 @@ Remote credentials (S3/R2 access keys) are stored separately in `~/.mnemo/creden
 ## Tests
 
 ```bash
-pip install "mnemo-agent[dev]"
+pip install "mnemo-agent[dev,s3]"
 pytest tests/ -v
 ```
 
+114 tests across `test_cli.py`, `test_remote.py`, and `test_server.py`.
+
 ---
 
 ## Roadmap
 
 - [x] Push/pull sync to S3, R2, and local filesystem remotes
+- [x] Write-time conflict detection with overwrite / keep-both / abort prompt
+- [x] Full MCP 2024-11-05 protocol — JSON-RPC 2.0 + stdio transport (Claude Desktop / Cursor)
 - [ ] Vector embeddings for semantic search (v2)
 - [ ] Parquet export for analytics
 - [ ] `mnemo audit` — fact provenance trace
 - [ ] Web UI dashboard
-- [ ] Native Ollama MCP client registration
 
 ---
 
@@ -323,13 +357,20 @@ pytest tests/ -v
 mnemo init --agent job-prep
 mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
 
-# Ask your agent questions via MCP (Ollama / Claude Code reads from :8080)
+# Connect to Claude Desktop (add to claude_desktop_config.json, then restart)
+mnemo serve --agent job-prep --stdio
+
+# Or run as an HTTP server for other MCP clients
 mnemo serve --agent job-prep --port 8080
 
 # After a practice interview, add what you learned
 mnemo add --fact "Lead with Supabase migration story at FAANG interviews" \
   --agent job-prep --attribute interview_tip --confidence 0.9 --tag tip
 
+# If you added a conflicting fact by mistake, retract it by ID prefix
+mnemo show --agent job-prep --format plain   # see IDs
+mnemo retract a1b2c3d4 --agent job-prep
+
 # Before next session, recall relevant context
 mnemo recall "React Supabase full-stack" --agent job-prep
 ```

{mnemo_agent-0.2.2 → mnemo_agent-0.3.1}/README.md

@@ -16,7 +16,7 @@ Inspired by Mnemosyne (Greek goddess of memory), **mnemo** is a portable CLI for
 - **TF-IDF search** — `mnemo recall "query"` with zero external ML deps, filterable by `--tag`
 - **Rich tables** — confidence color-coded (🟢 ≥0.8, 🟡 ≥0.5, 🔴 <0.5)
 - **HTML + graph diffs** — visual diff between dump snapshots
-- **MCP server** — FastAPI `/mcp/list_tools` + `/mcp/call_tool` for Ollama/Claude Code agents
+- **MCP server** — JSON-RPC 2.0 + stdio transport; plug directly into Claude Desktop, Cursor, or any MCP client
 - **Push/pull sync** — S3, Cloudflare R2, or local filesystem remote; timestamp-based merge
 - **Safe writes** — `--dry-run` on load, pull, and migrate
 
@@ -64,8 +64,10 @@ mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
 mnemo diff --agent-a job-prep --agent-b job-prep-v2
 mnemo diff dump1.json dump2.json --html diff_report.html
 
-# Start the MCP server (for Ollama / Claude Code agents)
+# Start the MCP server — HTTP mode
 mnemo serve --agent job-prep --port 8080
+# Or stdio mode (Claude Desktop / Cursor — no port needed)
+mnemo serve --agent job-prep --stdio
 
 # Sync to S3 (prompts for credentials on first add)
 mnemo remote add origin s3://my-bucket/mnemo --agent job-prep
@@ -91,7 +93,7 @@ mnemo pull --agent job-prep   # merges remote facts into local
 | `mnemo retract <fact-id> --agent <name>` | Remove a fact by ID or 8-char prefix |
 | `mnemo edit <fact-id> --agent <name>` | Edit value/attribute/confidence of an existing fact |
 | `mnemo migrate --dump f.json --target mem0 --agent name` | Migrate between providers |
-| `mnemo serve --agent <name> [--port 8080] [--read-only]` | MCP FastAPI server |
+| `mnemo serve --agent <name> [--port 8080] [--stdio] [--read-only]` | MCP server — HTTP (JSON-RPC 2.0) or stdio for Claude Desktop / Cursor |
 | `mnemo remote add <name> <url> --agent <name>` | Add a named remote (s3://, r2://, file://) |
 | `mnemo remote list --agent <name>` | List configured remotes |
 | `mnemo remote remove <name> --agent <name>` | Remove a remote |
@@ -111,13 +113,15 @@ mnemo-agent/
 │   ├── storage.py           # Local file I/O (JSON, YAML, credentials)
 │   ├── search.py            # TF-IDF search + diff engine
 │   ├── remotes.py           # Push/pull backends: FileBackend, S3Backend
-│   ├── server.py            # FastAPI MCP server
+│   ├── server.py            # FastAPI MCP server (HTTP + JSON-RPC 2.0)
+│   ├── stdio_server.py      # stdio MCP transport (Claude Desktop / Cursor)
 │   └── adapters/
 │       ├── mem0_adapter.py  # Mem0 API → normalized facts
 │       └── letta_adapter.py # Letta API → normalized facts
 ├── tests/
 │   ├── test_cli.py          # CLI command tests
 │   ├── test_remote.py       # Remote backends, merge, push/pull tests
+│   ├── test_server.py       # MCP server: JSON-RPC 2.0, tools, stdio transport
 │   └── fixtures/
 │       └── job_prep_sample.json
 ├── config.yaml              # Sample agent config
@@ -192,7 +196,28 @@ mnemo-agent/
 
 ---
 
-## 🔌 MCP Server (for Ollama / Claude Code)
+## 🔌 MCP Server
+
+mnemo implements the [MCP 2024-11-05 spec](https://spec.modelcontextprotocol.io) and supports two transports.
+
+### stdio — Claude Desktop / Cursor
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mnemo-job-prep": {
+      "command": "mnemo",
+      "args": ["serve", "--agent", "job-prep", "--stdio"]
+    }
+  }
+}
+```
+
+That's it — Claude Desktop will spawn mnemo as a subprocess and communicate over stdin/stdout.
+
+### HTTP — REST + JSON-RPC 2.0
 
 ```bash
 mnemo serve --agent job-prep --port 8080
@@ -200,20 +225,26 @@ mnemo serve --agent job-prep --port 8080
 
 | Endpoint | Description |
 |---|---|
-| `GET /mcp/list_tools` | List available tools (MCP schema) |
-| `POST /mcp/call_tool` | Call a tool by name with arguments |
-| `GET /facts` | REST: list all facts |
-| `GET /search?q=query` | REST: search memories |
+| `POST /` | JSON-RPC 2.0 — `initialize`, `tools/list`, `tools/call`, `ping` |
+| `GET /mcp/list_tools` | List available tools (legacy, kept for compatibility) |
+| `POST /mcp/call_tool` | Call a tool by name (legacy, kept for compatibility) |
+| `GET /facts` | REST: list all facts (`?entity=`, `?attribute=`, `?tag=`) |
+| `GET /search?q=query` | REST: search memories (`?tag=` filter supported) |
+| `GET /health` | Health check with version info |
 | `GET /docs` | Swagger UI |
 
 ### Available MCP tools
 
-```json
-{ "name": "search_memory",  "description": "TF-IDF search over agent memory" }
-{ "name": "list_facts",     "description": "Return all facts, optionally filtered" }
-{ "name": "upsert_fact",    "description": "Add a fact to agent memory" }
-{ "name": "get_agent_info", "description": "Agent metadata and fact count" }
-```
+| Tool | Description |
+|---|---|
+| `search_memory` | TF-IDF keyword search; supports `tag` filter |
+| `list_facts` | List all facts; filterable by `entity`, `attribute`, `tag`; shows IDs |
+| `upsert_fact` | Add a fact; supports `tags` array |
+| `retract_fact` | Remove a fact by ID or 8-char prefix |
+| `edit_fact` | Update a fact's `value`, `attribute`, or `confidence` |
+| `get_agent_info` | Agent name, fact count, last updated timestamp |
+
+`retract_fact` and `edit_fact` are disabled when `--read-only` is set.
 
 ---
 
@@ -253,20 +284,23 @@ Remote credentials (S3/R2 access keys) are stored separately in `~/.mnemo/creden
 ## Tests
 
 ```bash
-pip install "mnemo-agent[dev]"
+pip install "mnemo-agent[dev,s3]"
 pytest tests/ -v
 ```
 
+114 tests across `test_cli.py`, `test_remote.py`, and `test_server.py`.
+
 ---
 
 ## Roadmap
 
 - [x] Push/pull sync to S3, R2, and local filesystem remotes
+- [x] Write-time conflict detection with overwrite / keep-both / abort prompt
+- [x] Full MCP 2024-11-05 protocol — JSON-RPC 2.0 + stdio transport (Claude Desktop / Cursor)
 - [ ] Vector embeddings for semantic search (v2)
 - [ ] Parquet export for analytics
 - [ ] `mnemo audit` — fact provenance trace
 - [ ] Web UI dashboard
-- [ ] Native Ollama MCP client registration
 
 ---
 
@@ -277,13 +311,20 @@ pytest tests/ -v
 mnemo init --agent job-prep
 mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
 
-# Ask your agent questions via MCP (Ollama / Claude Code reads from :8080)
+# Connect to Claude Desktop (add to claude_desktop_config.json, then restart)
+mnemo serve --agent job-prep --stdio
+
+# Or run as an HTTP server for other MCP clients
 mnemo serve --agent job-prep --port 8080
 
 # After a practice interview, add what you learned
 mnemo add --fact "Lead with Supabase migration story at FAANG interviews" \
   --agent job-prep --attribute interview_tip --confidence 0.9 --tag tip
 
+# If you added a conflicting fact by mistake, retract it by ID prefix
+mnemo show --agent job-prep --format plain   # see IDs
+mnemo retract a1b2c3d4 --agent job-prep
+
 # Before next session, recall relevant context
 mnemo recall "React Supabase full-stack" --agent job-prep
 ```

{mnemo_agent-0.2.2 → mnemo_agent-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mnemo-agent"
-version = "0.2.2"
+version = "0.3.1"
 description = "Local-first agent memory CLI — dump, diff, migrate & query across Mem0, Letta, and more"
 readme = "README.md"
 requires-python = ">=3.12"

{mnemo_agent-0.2.2 → mnemo_agent-0.3.1}/src/mnemo/cli.py

@@ -827,6 +827,7 @@ def cmd_edit(
 
 
 @cli.command("add")
+@click.option("--force", "force", is_flag=True, default=False, help="Skip conflict check and keep both facts (useful for scripts)")
 @click.option("--fact", "-f", "fact_text", required=True, help="Free-text fact to store")
 @AGENT_OPTION
 @DIR_OPTION
@@ -844,8 +845,13 @@ def cmd_add(
     confidence: float,
     source: str,
     tags: tuple[str, ...],
+    force: bool,
 ) -> None:
-    """Add a fact to an agent's memory store."""
+    """Add a fact to an agent's memory store.
+
+    If an existing fact shares the same entity+attribute, you will be prompted
+    to overwrite it, keep both, or abort. Use --force to always keep both (for scripts).
+    """
     base = _resolve_base(mnemo_dir)
     ag = _resolve_agent(agent)
     require_agent(ag, base)
@@ -856,8 +862,42 @@ def cmd_add(
     except FileNotFoundError:
         dump = AgentDump(agent=ag)
 
+    resolved_entity = entity or ag
+
+    # ── Conflict detection ────────────────────────────────────────────────────
+    if not force:
+        conflicts = [
+            f for f in dump.facts
+            if f.entity.lower() == resolved_entity.lower()
+            and f.attribute.lower() == attribute.lower()
+        ]
+        if conflicts:
+            console.print(
+                f"\n[yellow]⚠  Conflict[/] — {len(conflicts)} existing fact(s) for "
+                f"[bold]{resolved_entity}[/].[cyan]{attribute}[/]:\n"
+            )
+            for c in conflicts:
+                color = _conf_color(c.confidence)
+                console.print(
+                    f"  [dim]{c.id[:8]}[/]  {c.value}  "
+                    f"[{color}](conf={c.confidence:.2f}, {c.timestamp.strftime('%Y-%m-%d')})[/]"
+                )
+            console.print()
+            choice = click.prompt(
+                "  Choice",
+                type=click.Choice(["o", "k", "a"], case_sensitive=False),
+                default="k",
+                prompt_suffix=" — [o] overwrite  [k] keep both  [a] abort: ",
+            )
+            if choice == "a":
+                console.print("[dim]Aborted.[/]")
+                return
+            if choice == "o":
+                conflict_ids = {c.id for c in conflicts}
+                dump.facts = [f for f in dump.facts if f.id not in conflict_ids]
+
     fact = Fact(
-        entity=entity or ag,
+        entity=resolved_entity,
         attribute=attribute,
         value=fact_text,
         source=source,  # type: ignore[arg-type]
@@ -881,12 +921,51 @@ def cmd_add(
 @click.option("--agent", "-a", required=True)
 @click.option("--port", "-p", default=8080, show_default=True)
 @click.option("--read-only", is_flag=True, help="Disable write endpoints")
+@click.option(
+    "--stdio",
+    "use_stdio",
+    is_flag=True,
+    help="Run in stdio mode (for Claude Desktop / Cursor MCP integration)",
+)
 @DIR_OPTION
-def cmd_serve(agent: str, port: int, read_only: bool, mnemo_dir: Path | None) -> None:
-    """Start the MCP-compatible FastAPI server for an agent."""
+def cmd_serve(agent: str, port: int, read_only: bool, use_stdio: bool, mnemo_dir: Path | None) -> None:
+    """Start the MCP server for an agent.
+
+    \b
+    HTTP mode (default) — REST + JSON-RPC 2.0 at POST /:
+      mnemo serve --agent job-prep --port 8080
+
+    \b
+    stdio mode — for Claude Desktop / Cursor integration:
+      mnemo serve --agent job-prep --stdio
+
+    \b
+    Claude Desktop config (~/.claude/claude_desktop_config.json):
+      {
+        "mcpServers": {
+          "mnemo-job-prep": {
+            "command": "mnemo",
+            "args": ["serve", "--agent", "job-prep", "--stdio"]
+          }
+        }
+      }
+    """
     base = _resolve_base(mnemo_dir)
     require_agent(agent, base)
 
+    if use_stdio:
+        # stdio transport — used by Claude Desktop, Cursor, etc.
+        # Print nothing to stdout (it's the JSON-RPC channel); use stderr for status.
+        import sys
+        print(
+            f"mnemo MCP stdio — agent={agent} read_only={read_only}",
+            file=sys.stderr,
+        )
+        from mnemo.stdio_server import run_stdio
+        run_stdio(agent=agent, base=base, read_only=read_only)
+        return
+
+    # HTTP transport
     try:
         import uvicorn  # type: ignore
     except ImportError:
@@ -896,13 +975,29 @@ def cmd_serve(agent: str, port: int, read_only: bool, mnemo_dir: Path | None) ->
 
     app = create_app(agent=agent, base=base, read_only=read_only)
 
+    import json as _json
+    desktop_cfg = _json.dumps(
+        {
+            "mcpServers": {
+                f"mnemo-{agent}": {
+                    "command": "mnemo",
+                    "args": ["serve", "--agent", agent, "--stdio"],
+                }
+            }
+        },
+        indent=2,
+    )
+
     console.print(
         Panel.fit(
             f"[bold cyan]Agent:[/]     {agent}\n"
             f"[bold cyan]Port:[/]      {port}\n"
             f"[bold cyan]Read-only:[/] {read_only}\n\n"
-            f"[dim]MCP tools:  http://localhost:{port}/mcp/list_tools[/]\n"
-            f"[dim]Docs:       http://localhost:{port}/docs[/]",
+            f"[dim]JSON-RPC 2.0:  POST http://localhost:{port}/[/]\n"
+            f"[dim]Tools list:    GET  http://localhost:{port}/mcp/list_tools[/]\n"
+            f"[dim]Docs:          http://localhost:{port}/docs[/]\n\n"
+            f"[bold]Claude Desktop config[/] [dim](~/.claude/claude_desktop_config.json)[/]:\n"
+            f"[dim]{desktop_cfg}[/]",
             title="🌐 mnemo serve",
             border_style="green",
         )