agentmem-mcp 0.1.0__py3-none-any.whl

agent_memory/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agent_memory/server.py

@@ -0,0 +1,155 @@
+from mcp.server.fastmcp import FastMCP
+from .storage import MemoryStorage, CATEGORIES
+
+mcp = FastMCP(
+    "agent-memory",
+    instructions=(
+        "Persistent graph-backed memory for AI agents. "
+        "Use `remember` to store facts, `recall` to search, "
+        "`get_related` to traverse the memory graph, "
+        "`list_memories` to browse by category, `forget` to delete."
+    ),
+)
+
+_store = MemoryStorage()
+
+
+@mcp.tool()
+def remember(content: str, category: str = "fact", tags: str = "") -> str:
+    """Store a memory and auto-link it to related existing memories.
+
+    Args:
+        content: The fact, observation, or decision to remember.
+        category: One of fact, tool, preference, context, relationship, task, decision.
+        tags: Comma-separated keywords for later retrieval.
+    """
+    if category not in CATEGORIES:
+        category = "fact"
+    mid = _store.add(content, category, tags)
+    edges = _store.edges(mid)
+    result = f"Stored [{mid}] ({category}): {content}"
+    if edges:
+        linked = [f"{r} → [{eid}]" for r, eid, _, _ in edges[:3]]
+        result += f"\nAuto-linked: {', '.join(linked)}"
+    return result
+
+
+@mcp.tool()
+def recall(query: str, limit: int = 8) -> str:
+    """Search memories by keyword and return matches with their graph connections.
+
+    Args:
+        query: Keywords to search for.
+        limit: Maximum number of memories to return (default 8).
+    """
+    rows = _store.search(query, min(limit, 20))
+    if not rows:
+        return f"No memories found for: {query}"
+
+    lines = [f"Found {len(rows)} memory/memories for '{query}':\n"]
+    for mid, content, category, tags, created_at in rows:
+        lines.append(f"[{mid}] ({category}) {content}")
+        if tags:
+            lines.append(f"  tags: {tags}")
+        edges = _store.edges(mid)
+        if edges:
+            for rel, eid, econtent, _ in edges[:2]:
+                lines.append(f"  -{rel}→ [{eid}] {econtent[:60]}...")
+        lines.append("")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_related(memory_id: str, depth: int = 2) -> str:
+    """Traverse the memory graph outward from a specific memory.
+
+    Args:
+        memory_id: The ID of the memory to start traversal from.
+        depth: How many hops to traverse (1–3, default 2).
+    """
+    root = _store.get(memory_id)
+    if not root:
+        return f"Memory [{memory_id}] not found."
+
+    depth = max(1, min(depth, 3))
+    visited = {memory_id}
+    lines = [f"Graph from [{memory_id}]: {root[1]}\n"]
+    queue = [(memory_id, 0)]
+
+    while queue:
+        mid, d = queue.pop(0)
+        if d >= depth:
+            continue
+        for rel, eid, econtent, ecat in _store.edges(mid):
+            marker = "  " * (d + 1)
+            lines.append(f"{marker}-{rel}→ [{eid}] ({ecat}) {econtent}")
+            if eid not in visited:
+                visited.add(eid)
+                queue.append((eid, d + 1))
+
+    if len(lines) == 2:
+        lines.append("  (no connected memories)")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def link_memories(source_id: str, target_id: str, relationship: str) -> str:
+    """Manually create a typed edge between two memories.
+
+    Args:
+        source_id: The source memory ID.
+        target_id: The target memory ID.
+        relationship: Relationship type, e.g. DEPENDS_ON, SUPPORTS, CONTRADICTS, PRECEDES.
+    """
+    if not _store.get(source_id):
+        return f"Memory [{source_id}] not found."
+    if not _store.get(target_id):
+        return f"Memory [{target_id}] not found."
+    ok = _store.link(source_id, target_id, relationship)
+    if ok:
+        return f"Linked [{source_id}] -{relationship.upper()}→ [{target_id}]"
+    return f"Edge already exists or could not be created."
+
+
+@mcp.tool()
+def list_memories(category: str = "", limit: int = 20) -> str:
+    """List stored memories, optionally filtered by category.
+
+    Args:
+        category: Filter to one of: fact, tool, preference, context, relationship, task, decision.
+        limit: Maximum memories to return (default 20).
+    """
+    rows = _store.list_all(category, min(limit, 50))
+    if not rows:
+        label = f" in category '{category}'" if category else ""
+        return f"No memories{label}."
+
+    stats = _store.stats()
+    header = (
+        f"{stats['memories']} total memories · {stats['edges']} edges"
+        + (f" · showing '{category}'" if category else "")
+        + "\n"
+    )
+    lines = [header]
+    for mid, content, cat, tags, created_at in rows:
+        ts = created_at[:10]
+        lines.append(f"[{mid}] {ts} ({cat}) {content}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def forget(memory_id: str) -> str:
+    """Delete a memory and all its graph edges.
+
+    Args:
+        memory_id: The ID of the memory to delete.
+    """
+    row = _store.get(memory_id)
+    if not row:
+        return f"Memory [{memory_id}] not found."
+    _store.delete(memory_id)
+    return f"Deleted [{memory_id}]: {row[1]}"
+
+
+def main():
+    mcp.run()

agent_memory/storage.py

@@ -0,0 +1,148 @@
+import sqlite3
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+STOP_WORDS = {
+    "a", "an", "the", "is", "in", "it", "of", "to", "and", "or", "for",
+    "with", "on", "at", "from", "by", "as", "be", "was", "are", "has",
+    "have", "had", "not", "this", "that", "i", "you", "we", "they",
+}
+
+CATEGORIES = ("fact", "tool", "preference", "context", "relationship", "task", "decision")
+
+
+class MemoryStorage:
+    def __init__(self, db_path: str = None):
+        if db_path is None:
+            db_path = Path.home() / ".agent-memory" / "memories.db"
+        path = Path(db_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn = sqlite3.connect(str(path), check_same_thread=False)
+        self._init()
+
+    def _init(self):
+        self.conn.executescript("""
+            CREATE TABLE IF NOT EXISTS memories (
+                id       TEXT PRIMARY KEY,
+                content  TEXT NOT NULL,
+                category TEXT DEFAULT 'fact',
+                tags     TEXT DEFAULT '',
+                created_at TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS edges (
+                id           TEXT PRIMARY KEY,
+                source_id    TEXT NOT NULL,
+                target_id    TEXT NOT NULL,
+                relationship TEXT NOT NULL,
+                created_at   TEXT NOT NULL,
+                UNIQUE(source_id, target_id, relationship),
+                FOREIGN KEY (source_id) REFERENCES memories(id) ON DELETE CASCADE,
+                FOREIGN KEY (target_id) REFERENCES memories(id) ON DELETE CASCADE
+            );
+            PRAGMA foreign_keys = ON;
+            CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
+            CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
+            CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+        """)
+        self.conn.commit()
+
+    def _new_id(self) -> str:
+        return str(uuid.uuid4())[:8]
+
+    def add(self, content: str, category: str, tags: str) -> str:
+        mid = self._new_id()
+        self.conn.execute(
+            "INSERT INTO memories VALUES (?, ?, ?, ?, ?)",
+            (mid, content, category, tags, datetime.utcnow().isoformat()),
+        )
+        self.conn.commit()
+        self._auto_link(mid, content)
+        return mid
+
+    def _auto_link(self, new_id: str, content: str):
+        words = {w for w in content.lower().split() if w not in STOP_WORDS and len(w) > 3}
+        seen = set()
+        for word in list(words)[:6]:
+            rows = self.conn.execute(
+                "SELECT id FROM memories WHERE LOWER(content) LIKE ? AND id != ? LIMIT 4",
+                (f"%{word}%", new_id),
+            ).fetchall()
+            for (rid,) in rows:
+                if rid not in seen:
+                    seen.add(rid)
+                    eid = self._new_id()
+                    self.conn.execute(
+                        "INSERT OR IGNORE INTO edges VALUES (?, ?, ?, 'RELATES_TO', ?)",
+                        (eid, new_id, rid, datetime.utcnow().isoformat()),
+                    )
+        if seen:
+            self.conn.commit()
+
+    def link(self, source_id: str, target_id: str, relationship: str) -> bool:
+        eid = self._new_id()
+        try:
+            self.conn.execute(
+                "INSERT OR IGNORE INTO edges VALUES (?, ?, ?, ?, ?)",
+                (eid, source_id, target_id, relationship.upper(), datetime.utcnow().isoformat()),
+            )
+            self.conn.commit()
+            return True
+        except Exception:
+            return False
+
+    def search(self, query: str, limit: int = 10) -> list:
+        terms = [t for t in query.lower().split() if t not in STOP_WORDS]
+        if not terms:
+            terms = query.lower().split()
+        conditions = " OR ".join(["LOWER(content) LIKE ?" for _ in terms])
+        params = [f"%{t}%" for t in terms] + [limit]
+        return self.conn.execute(
+            f"SELECT id, content, category, tags, created_at FROM memories "
+            f"WHERE {conditions} ORDER BY created_at DESC LIMIT ?",
+            params,
+        ).fetchall()
+
+    def get(self, mid: str) -> tuple | None:
+        return self.conn.execute(
+            "SELECT id, content, category, tags, created_at FROM memories WHERE id = ?",
+            (mid,),
+        ).fetchone()
+
+    def edges(self, mid: str) -> list:
+        return self.conn.execute(
+            """SELECT e.relationship, m.id, m.content, m.category
+               FROM edges e JOIN memories m ON e.target_id = m.id
+               WHERE e.source_id = ?
+               UNION
+               SELECT e.relationship, m.id, m.content, m.category
+               FROM edges e JOIN memories m ON e.source_id = m.id
+               WHERE e.target_id = ?""",
+            (mid, mid),
+        ).fetchall()
+
+    def list_all(self, category: str = "", limit: int = 20) -> list:
+        if category:
+            return self.conn.execute(
+                "SELECT id, content, category, tags, created_at FROM memories "
+                "WHERE category = ? ORDER BY created_at DESC LIMIT ?",
+                (category, limit),
+            ).fetchall()
+        return self.conn.execute(
+            "SELECT id, content, category, tags, created_at FROM memories "
+            "ORDER BY created_at DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+
+    def delete(self, mid: str) -> bool:
+        cur = self.conn.execute("DELETE FROM memories WHERE id = ?", (mid,))
+        self.conn.commit()
+        return cur.rowcount > 0
+
+    def stats(self) -> dict:
+        m = self.conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        e = self.conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+        cats = self.conn.execute(
+            "SELECT category, COUNT(*) FROM memories GROUP BY category"
+        ).fetchall()
+        return {"memories": m, "edges": e, "by_category": dict(cats)}

agentmem_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: agentmem-mcp
+Version: 0.1.0
+Summary: Persistent graph-backed memory for AI agents via MCP — store, traverse, and recall knowledge across sessions
+Project-URL: Homepage, https://graphifymd.com
+Project-URL: Repository, https://github.com/Yarmoluk/agent-memory-mcp
+Project-URL: Issues, https://github.com/Yarmoluk/agent-memory-mcp/issues
+Author-email: Daniel Yarmoluk <daniel.yarmoluk@gmail.com>
+License: MIT
+Keywords: agent,agentiq,ai-agents,fastmcp,knowledge-graph,llm,mcp,memory,nvidia,persistent-memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# agent-memory-mcp
+
+**Give your agents memory. Give them direction. Open the context window.**
+
+The context window is the most expensive real estate in AI development. Most teams fill it with the same documents, the same re-derived dependencies, the same facts the agent already knew from last session. The window bloats. The cost compounds. The agent still starts from scratch.
+
+`agent-memory-mcp` solves the other half of the problem.
+
+Not retrieval — traversal. Your agent doesn't search for what looks similar. It walks declared relationships: what came before, what depends on what, what decision caused what outcome. Persistent across sessions. Zero external services. One config entry.
+
+Combined with a sealed knowledge appliance ([ckg-mcp](https://pypi.org/project/ckg-mcp/)), your agent has both layers of what a production system needs: memory for what it *did*, and structured knowledge for what's *true*. That's not a wider context window — that's a smarter one.
+
+[![PyPI](https://img.shields.io/pypi/v/agent-memory-mcp)](https://pypi.org/project/agent-memory-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+![agent-memory-mcp architecture](assets/graph.svg)
+
+> ⭐ **If this saves you tokens, star it** — it's how other developers find it.
+
+---
+
+## The problem
+
+Most teams give their agents a document dump and call it knowledge. Most agents start every session with no sense of where they've been. The result:
+
+- Re-explaining your stack, your preferences, your constraints — every session
+- Re-discovering which tool worked and which didn't
+- Re-fetching context the agent already built last time
+- Burning tokens on what the agent already knew
+- No memory of decisions made, no record of what was tried and failed
+
+This isn't a model problem. It's a memory architecture problem — and it compounds with every agent call you pay for.
+
+---
+
+## Install
+
+```bash
+# Run directly — no install needed
+uvx agent-memory-mcp
+
+# Or install
+pip install agent-memory-mcp
+```
+
+---
+
+## MCP config
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "uvx",
+      "args": ["agent-memory-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / NVIDIA AgentIQ
+
+Same config — drop it in your `mcp_servers.json`. Any MCP-compatible client works.
+
+Memories persist to `~/.agent-memory/memories.db` — SQLite, no external services, no API keys.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `remember(content, category, tags)` | Store a memory. Auto-links to related existing memories. |
+| `recall(query, limit)` | Search by keyword. Returns matches with their graph connections. |
+| `get_related(memory_id, depth)` | Traverse the graph outward 1–3 hops from a memory. |
+| `link_memories(source, target, relationship)` | Declare a typed edge between two memories. |
+| `list_memories(category, limit)` | Browse by category: fact, tool, decision, preference, context… |
+| `forget(memory_id)` | Delete a memory and all its edges. |
+
+**Categories:** `fact` · `tool` · `preference` · `context` · `relationship` · `task` · `decision`
+
+**Edge types:** `DEPENDS_ON` · `SUPPORTS` · `CONTRADICTS` · `PRECEDES` · `CAUSES` · `RELATES_TO`
+
+---
+
+## Usage patterns
+
+### 1. Cross-session continuity
+
+The agent picks up where it left off — no re-introduction needed.
+
+```
+Session 1:
+  remember("User prefers FastAPI over Flask", "preference", ["python", "api"])
+  remember("Project uses Postgres 15 on Supabase", "fact", ["database"])
+  remember("Avoid Alembic — use raw migrations", "preference", ["database"])
+
+Session 2:
+  recall("database preferences")
+  → Returns Postgres fact + Alembic preference with RELATES_TO edge between them
+```
+
+### 2. Dependency chain memory
+
+The agent stores what it discovered about your stack — so it doesn't re-discover it.
+
+```
+remember("TensorRT requires CUDA 11.8+", "fact", ["tensorrt", "cuda"])
+remember("CUDA 11.8 install requires gcc 9+", "fact", ["cuda", "build"])
+link_memories(tensorrt_id, cuda_id, "DEPENDS_ON")
+link_memories(cuda_id, gcc_id, "DEPENDS_ON")
+
+→ get_related(tensorrt_id, depth=3) returns the full dependency chain
+```
+
+### 3. Decision trail
+
+The agent remembers why it made a choice — not just what it chose.
+
+```
+remember("Chose ChromaDB over Pinecone: latency and no API key requirement", "decision", ["vector-db"])
+remember("Pinecone rejected: requires API key in CI environment", "context", ["vector-db", "ci"])
+link_memories(decision_id, context_id, "CAUSES")
+
+→ Three months later: recall("vector db decision") surfaces both with the causal link
+```
+
+### 4. Tool performance learning
+
+The agent tracks what worked — and what didn't.
+
+```
+remember("exa_search returns better results than web_search for technical docs", "tool", ["search"])
+remember("brave_search rate-limited after 10 calls/min in production", "tool", ["search", "production"])
+
+→ Before next search: recall("search tools") returns ranked performance memories
+```
+
+### 5. Multi-step task tracking
+
+The agent tracks where a long-running task is — even across sessions.
+
+```
+remember("Migration step 1/4 complete: users table done", "task", ["migration", "postgres"])
+remember("Step 2/4 blocked: foreign key constraint on orders table", "task", ["migration", "blocker"])
+link_memories(step1_id, step2_id, "PRECEDES")
+
+→ Next session: recall("migration status") returns the full chain with the blocker flagged
+```
+
+### 6. Pair with a sealed knowledge appliance (CKG)
+
+Memory tells the agent what it **did**. Knowledge tells it what's **true**.
+
+```
+# Memory: agent remembers what it tried
+remember("NIM deployment failed on t3.medium: insufficient VRAM", "fact", ["nim", "aws"])
+
+# Knowledge: CKG tells it the dependency chain it should have known
+query_ckg("NIM", "nvidia-nim", depth=3)
+→ NIM → TensorRT-LLM → GPU Memory ≥24GB → A10G minimum
+```
+
+The agent now has both: its own experience (memory) and the declared domain rules (knowledge).
+
+See [ckg-mcp](https://pypi.org/project/ckg-mcp/) — 97 domains of sealed knowledge appliances, or build your own at [graphifymd.com/caas](https://graphifymd.com/caas).
+
+---
+
+## Context compression and optimization
+
+This is the underlying problem agent-memory-mcp solves — not just "memory."
+
+**The standard approach:** inject raw documents into the context window. 2,982 tokens to answer one question about your stack. Every call. Every session.
+
+**The graph approach:** traverse declared relationships. 269 tokens for the same answer — the exact chain, nothing more.
+
+That's **11× context compression**. Not by summarizing or chunking. By replacing document retrieval with graph traversal. You don't inject a manual — you walk a map.
+
+Context optimization means the agent gets *exactly* what it needs to reason:
+- Not "here are 40 pages about CUDA" — but "NIM → TensorRT → CUDA 11.8+ → Hopper SM90"
+- Not "here are your last 200 conversation turns" — but the 3 decisions that led to this moment
+- Not similarity guesses — declared edges the agent itself wrote
+
+The result: smaller prompts, faster responses, lower cost, and an agent that reasons rather than retrieves.
+
+---
+
+## Why graph, not vector?
+
+Vector similarity finds *related* content. Graph traversal finds *declared* connections.
+
+| | Vector | Graph |
+|---|---|---|
+| How it works | Embedding similarity | Declared typed edges |
+| Best for | Fuzzy recall, semantic search | Reasoning chains, dependency traversal |
+| Answer to "what came before X?" | Approximation | Exact traversal |
+| Can be wrong? | Yes — guesses | No — only returns declared edges |
+
+`agent-memory-mcp` auto-links new memories to related existing ones on write (via keyword overlap), then lets you declare precise typed edges when the relationship matters.
+
+**The graph doesn't guess. It traverses.**
+
+---
+
+## Benchmark
+
+Memory quality benchmarked against [KRB Benchmark v0.6.2](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf):
+
+| System | F1 | Tokens/query |
+|---|---|---|
+| **CKG graph traversal** | **0.471** | **269** |
+| RAG (vector retrieval) | 0.123 | 2,982 |
+| GraphRAG | 0.120 | — |
+
+~4× F1 · 11× fewer tokens · auditable by design
+
+---
+
+## Pair it with domain knowledge
+
+agent-memory-mcp handles what your agent **experiences**. [ckg-mcp](https://pypi.org/project/ckg-mcp/) handles what your agent **knows**.
+
+```bash
+pip install ckg-mcp
+```
+
+97 domains ready to query: NVIDIA AI stack, financial regulations, healthcare standards, manufacturing safety, legal frameworks, and more. Free tier included.
+
+**[→ Browse domains and pricing at graphifymd.com/caas](https://graphifymd.com/caas)**
+
+---
+
+## Partners and integrations
+
+We're looking for:
+
+- **MCP client integrations** — if you're building an agent runtime that supports MCP, we'd like to be in your default toolchain
+- **Domain experts** — if you have proprietary knowledge that would be more useful as a traversable graph than a document corpus, let's talk
+- **Enterprise pilots** — regulated industries (finance, healthcare, manufacturing, legal) where agents need auditable, declared knowledge rather than probabilistic retrieval
+- **Researchers** — working on agent memory, knowledge representation, or MCP tooling
+
+Reach out: [graphifymd.com](https://graphifymd.com) · [daniel.yarmoluk@gmail.com](mailto:daniel.yarmoluk@gmail.com)
+
+---
+
+## Related
+
+- **[ckg-mcp](https://pypi.org/project/ckg-mcp/)** — 97 sealed knowledge appliances via MCP
+- **[ckg-nvidia-ai](https://github.com/Yarmoluk/ckg-nvidia-ai)** — 20 NVIDIA AI domain graphs, 998 nodes, free
+- **[KRB Benchmark](https://huggingface.co/datasets/danyarm/ckg-benchmark)** — open benchmark dataset
+- **[graphifymd.com/caas](https://graphifymd.com/caas)** — Context-as-a-Service: build or subscribe to sealed knowledge appliances
+
+---
+
+## License
+
+MIT — built by [Graphify.md](https://graphifymd.com). Patent pending.

agentmem_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_memory/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+agent_memory/server.py,sha256=_SutIjoRWey-VA6M5WWIjyI7xrSy988FmMQChANNQNA,4965
+agent_memory/storage.py,sha256=u3keZuwg3ru51fItsCoUGyqRkkJypQqc_Zo1o3bEgIA,5911
+agentmem_mcp-0.1.0.dist-info/METADATA,sha256=gKZAkg_SYo1PdhaJ8ojcukgc3BdCdN4U5i7B4d669WE,10972
+agentmem_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentmem_mcp-0.1.0.dist-info/entry_points.txt,sha256=pqvzbM_eaP4kKPWjMcXXTkhjHib7YVwJMN5sIhaywoA,58
+agentmem_mcp-0.1.0.dist-info/RECORD,,

agentmem_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

agentmem_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-memory = agent_memory.server:main