WS-C: CogniFold MCP server + integration docs

docs/INTEGRATIONS.md

@@ -0,0 +1,198 @@
+# CogniFold Integrations
+
+CogniFold can plug into external tools as a persistent memory layer. This page
+documents the supported integrations and roadmap.
+
+## MCP (Model Context Protocol)
+
+CogniFold ships an MCP server that exposes its persistent concept-graph memory
+to any MCP client — Claude Code, Claude Desktop, Cursor, and others. The server
+wraps CogniFold's existing in-process logic (the ingestion `Pipeline` and the
+`MemoryQueryAgent`); it does not reimplement memory.
+
+### Install
+
+```bash
+pip install 'cognifold[mcp]'
+```
+
+This pulls in the official `mcp` Python SDK alongside CogniFold. For LLM-based
+concept folding you also want an API key and (optionally) the agent extra:
+
+```bash
+pip install 'cognifold[mcp,agent]'
+```
+
+### Tools
+
+| Tool | Description |
+| --- | --- |
+| `cognifold_remember(text, timestamp?)` | Ingest an observation/fact/event into the persistent graph. Returns the graph deltas (nodes/edges added, concepts created). |
+| `cognifold_query(question, max_nodes?)` | Retrieve relevant context from memory for a question. Returns assembled context + supporting nodes. |
+| `cognifold_graph_stats()` | Node/edge counts by type (events, concepts, intents, time nodes). |
+| `cognifold_list_intents()` | Current intents (goals/desires) with id, status, and description. |
+
+### Running the server
+
+The server speaks MCP over stdio. Either entry point works:
+
+```bash
+python -m cognifold.mcp
+# or
+cognifold-mcp
+```
+
+`cognifold-mcp --help` prints usage and the environment variables it reads.
+
+### Environment variables
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `COGNIFOLD_MCP_GRAPH` | Path where the graph JSON is persisted (so memory survives restarts). | `~/.cognifold/mcp_graph.json` |
+| `COGNIFOLD_MODEL__NAME` | LLM model used for concept folding during `remember`. | `gemini-2.5-flash` |
+| `GOOGLE_API_KEY` | API key for Gemini models. | — |
+| `OPENAI_API_KEY` | API key for OpenAI models. | — |
+
+If no API key is set, `cognifold_remember` still works — it falls back to a
+default plan that stores the raw event as a node (no LLM-based concept
+extraction).
+
+### Claude Desktop
+
+Add CogniFold to `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "cognifold": {
+      "command": "cognifold-mcp",
+      "env": {
+        "COGNIFOLD_MCP_GRAPH": "/Users/you/.cognifold/mcp_graph.json",
+        "COGNIFOLD_MODEL__NAME": "gemini-2.5-flash",
+        "GOOGLE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+If `cognifold-mcp` is not on Claude Desktop's `PATH`, use the module form with
+an explicit interpreter:
+
+```json
+{
+  "mcpServers": {
+    "cognifold": {
+      "command": "python",
+      "args": ["-m", "cognifold.mcp"],
+      "env": {
+        "COGNIFOLD_MCP_GRAPH": "/Users/you/.cognifold/mcp_graph.json",
+        "GOOGLE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing the config.
+
+### Claude Code
+
+Register the server with the CLI:
+
+```bash
+claude mcp add cognifold \
+  --env COGNIFOLD_MCP_GRAPH=$HOME/.cognifold/mcp_graph.json \
+  --env COGNIFOLD_MODEL__NAME=gemini-2.5-flash \
+  --env GOOGLE_API_KEY=your-key-here \
+  -- cognifold-mcp
+```
+
+Or commit a project-scoped `.mcp.json` to the repo root:
+
+```json
+{
+  "mcpServers": {
+    "cognifold": {
+      "command": "cognifold-mcp",
+      "env": {
+        "COGNIFOLD_MCP_GRAPH": ".cognifold/mcp_graph.json",
+        "COGNIFOLD_MODEL__NAME": "gemini-2.5-flash",
+        "GOOGLE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Cursor reads the same MCP server schema. Add to
+`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "cognifold": {
+      "command": "cognifold-mcp",
+      "env": {
+        "COGNIFOLD_MCP_GRAPH": "/Users/you/.cognifold/mcp_graph.json",
+        "GOOGLE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Example round trip
+
+Once the server is registered, the client's model can call the tools:
+
+```
+> cognifold_remember(text="Started using CogniFold as a memory layer for my
+                           research notes on 2026-06-18.")
+
+{
+  "event_id": "evt-1a2b3c4d5e6f",
+  "success": true,
+  "nodes_added": 3,
+  "edges_added": 2,
+  "concepts_created": ["cognifold-memory-layer", "research-notes"],
+  "total_nodes": 3,
+  "total_edges": 2,
+  "graph_path": "/Users/you/.cognifold/mcp_graph.json"
+}
+
+> cognifold_query(question="What am I using CogniFold for?")
+
+{
+  "question": "What am I using CogniFold for?",
+  "context": "CONCEPTS:\n- CogniFold memory layer: used for research notes ...",
+  "supporting_nodes": [
+    {"node_id": "...", "type": "concept", "title": "CogniFold memory layer",
+     "relevance": 0.91, "description": "Memory layer for research notes"}
+  ],
+  "nodes_scanned": 3,
+  "query_time_ms": 4.2
+}
+```
+
+The memory persists at `COGNIFOLD_MCP_GRAPH`, so a follow-up `cognifold_query`
+in a later session still recalls these facts.
+
+---
+
+## Roadmap (Planned)
+
+The following integrations are **planned** and not yet implemented:
+
+- **OpenAI-compatible API** — _Planned._ A drop-in `/v1`-style HTTP surface so
+  CogniFold memory can be used by any OpenAI-compatible client/SDK.
+- **LangChain `BaseMemory`** — _Planned._ A `BaseMemory` subclass backed by
+  CogniFold so LangChain chains/agents can read and write the concept graph.
+- **LlamaIndex retriever** — _Planned._ A `BaseRetriever` implementation that
+  queries the CogniFold graph for use in LlamaIndex query engines.
+
+Contributions welcome — these wrap the same in-process `Pipeline` /
+`MemoryQueryAgent` seams the MCP server already uses.

pyproject.toml

@@ -3,7 +3,7 @@ name = "cognifold"
 version = "0.1.0"
 description = "A dynamic concept graph system that processes real-time event streams and maintains an evolving knowledge representation"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "networkx>=3.2",
     "numpy>=2.0.2",
@@ -17,6 +17,7 @@ dependencies = [
 
 [project.scripts]
 cognifold = "cognifold.cli:main"
+cognifold-mcp = "cognifold.mcp:main"
 
 [project.optional-dependencies]
 dev = [
@@ -37,6 +38,9 @@ viz = [
 search = [
     "faiss-cpu>=1.7",
 ]
+mcp = [
+    "mcp>=1.0",
+]
 service = [
     "fastapi>=0.109",
     "uvicorn[standard]>=0.27",

src/cognifold/mcp/__init__.py

@@ -0,0 +1,26 @@
+"""Model Context Protocol (MCP) server for CogniFold.
+
+Exposes CogniFold's persistent concept-graph memory as an MCP server so it
+plugs into Claude Code, Claude Desktop, Cursor, and any other MCP client.
+
+The server wraps the existing in-process logic (``Pipeline`` for ingestion,
+``MemoryQueryAgent`` for retrieval, ``ConceptGraph`` metrics for stats). It does
+not reimplement memory — it is a thin adapter over the same code paths the
+HTTP service uses.
+
+Run it as a stdio server::
+
+    python -m cognifold.mcp
+    # or, if installed with the console script:
+    cognifold-mcp
+
+Install the optional dependency first::
+
+    pip install 'cognifold[mcp]'
+"""
+
+from __future__ import annotations
+
+from cognifold.mcp.server import build_server, main
+
+__all__ = ["build_server", "main"]

src/cognifold/mcp/__main__.py

@@ -0,0 +1,16 @@
+"""``python -m cognifold.mcp`` entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from cognifold.mcp.server import main
+
+if __name__ == "__main__":
+    try:
+        main()
+    except RuntimeError as exc:
+        # Surface the "pip install 'cognifold[mcp]'" hint cleanly instead of a
+        # traceback when the MCP SDK is not installed.
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)