{"_id":"@eidetic-labs/stigmem-mcp","name":"@eidetic-labs/stigmem-mcp","dist-tags":{"alpha":"0.1.0","latest":"0.1.0"},"versions":{"0.1.0":{"name":"@eidetic-labs/stigmem-mcp","version":"0.1.0","description":"MCP server for Stigmem — exposes assert_fact, query_facts, recall, resolve_contradiction, subscribe_scope, and lint_scope","type":"module","bin":{"stigmem-mcp":"dist/server.js"},"main":"./dist/server.js","types":"./dist/server.d.ts","scripts":{"build":"tsc && chmod +x dist/server.js","start":"node dist/server.js","dev":"tsx src/server.ts","type-check":"tsc --noEmit","test":"vitest run src/server.test.ts"},"license":"Apache-2.0","author":{"name":"Eidetic Labs","email":"oss@eidetic-labs.ai"},"repository":{"type":"git","url":"git+https://github.com/eidetic-labs/stigmem.git","directory":"adapters/mcp"},"homepage":"https://github.com/eidetic-labs/stigmem/tree/main/features/mcp-adapter#readme","bugs":{"url":"https://github.com/eidetic-labs/stigmem/issues"},"keywords":["stigmem","mcp","model-context-protocol","agents","memory"],"publishConfig":{"access":"public","provenance":true},"dependencies":{"@eidetic-labs/stigmem-ts":"^0.9.0-alpha.8","@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.0"},"devDependencies":{"@types/node":"^20.0.0","@vitest/coverage-v8":"^4.1.0","tsx":"^4.7.0","typescript":"^5.4.0","vite":"^6.3.0","vitest":"^4.1.0"},"gitHead":"b86813e18129f9d3eb1653fe51190b0476308a09","_id":"@eidetic-labs/stigmem-mcp@0.1.0","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-DEGnbMLTbXmClbeGJcok3F7ylJ7wS0n686R3ZLA2cP6Zx6bcX9axTkA8NwaGkmStn0EjuGuNkugSz0Ksyt1Buw==","shasum":"7aa71c1970ad92df794a370366e0c19689a53002","tarball":"https://registry.npmjs.org/@eidetic-labs/stigmem-mcp/-/stigmem-mcp-0.1.0.tgz","fileCount":5,"unpackedSize":46602,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFRRzOiF6DTsBpYyIHlqv5kDmh35CpI95tlQJCaE+qe5AiAtH/WFwBpokArYDNXeswsBYBlFrvXp1qdnm3DuYF6J6A=="}]},"_npmUser":{"name":"offbyonce","email":"barry.jones20@gmail.com"},"directories":{},"maintainers":[{"name":"offbyonce","email":"barry.jones20@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stigmem-mcp_0.1.0_1779676696177_0.7972089935718243"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T02:38:16.043Z","0.1.0":"2026-05-25T02:38:16.382Z","modified":"2026-05-25T02:38:16.590Z"},"maintainers":[{"name":"offbyonce","email":"barry.jones20@gmail.com"}],"description":"MCP server for Stigmem — exposes assert_fact, query_facts, recall, resolve_contradiction, subscribe_scope, and lint_scope","homepage":"https://github.com/eidetic-labs/stigmem/tree/main/features/mcp-adapter#readme","keywords":["stigmem","mcp","model-context-protocol","agents","memory"],"repository":{"type":"git","url":"git+https://github.com/eidetic-labs/stigmem.git","directory":"adapters/mcp"},"author":{"name":"Eidetic Labs","email":"oss@eidetic-labs.ai"},"bugs":{"url":"https://github.com/eidetic-labs/stigmem/issues"},"license":"Apache-2.0","readme":"# Stigmem MCP Server\n\nExposes [Stigmem](../../README.md) as an [MCP](https://modelcontextprotocol.io) server.\nAny stdio-capable MCP host can launch this adapter, but the `0.1.0`\npublication gate only validates Codex CLI, Claude Code, and the repo-local MCP\nprotocol smoke. Gemini CLI has passed MCP tool execution with a host\nfinal-response caveat. Continue.dev, Cursor, Zed, and custom-host connector use\nis experimental until a host-specific smoke record exists.\n\n## Tools exposed\n\n| Tool | Description |\n|---|---|\n| `assert_fact` | Write a typed fact to the node |\n| `query_facts` | Query facts by entity / relation / scope |\n| `recall` | Retrieve channel-separated recall context |\n| `resolve_contradiction` | Resolve a contradiction between two conflicting facts |\n| `subscribe_scope` | Poll for recent facts in a scope (single-shot, cursor-based) |\n| `lint_scope` | Health-check sweep — detect contradictions, stale facts, orphans, broken refs (read-only; `Spec-20-Lint-Semantics`) |\n\n## Validation tiers\n\n| Editor | Tier | Guide |\n|---|---|---|\n| Codex CLI | Validated | [Codex CLI](../../docs/docs/integrations/mcp/codex-cli.md) |\n| Claude Code | Validated | [Claude Code](../../docs/docs/integrations/mcp/claude-code.md) |\n| Gemini CLI | Caveated | [Gemini CLI](../../docs/docs/integrations/mcp/gemini-cli.md) |\n| Continue.dev | Experimental | [Continue.dev](../../docs/docs/integrations/mcp/continue-dev.md) |\n| Cursor | Experimental | [Cursor](../../docs/docs/integrations/mcp/cursor.md) |\n| Zed | Experimental | [Zed](../../docs/docs/integrations/mcp/zed.md) |\n\n## Setup\n\n### Requirements\n\n- Node.js ≥ 18\n- A running Stigmem node (see `stigmem/node/README.md`)\n\n### Install\n\n```bash\nnpm install -g @eidetic-labs/stigmem-mcp\n# or, ephemeral:\nnpx -y @eidetic-labs/stigmem-mcp@0.1.0\n```\n\nFor local development:\n\n```bash\ncd stigmem/adapters/mcp\npnpm install\npnpm build\n```\n\nThe npm package is versioned independently from the Stigmem project release\nline. Continue.dev, Cursor, and Zed guides remain unvalidated for this package\nstate. Gemini CLI users should review the host caveat in the MCP smoke record\nbefore relying on clean final-response rendering.\n\n### Configure in Claude Code\n\nAdd to `.claude/mcp_servers.json` (or the global MCP config):\n\n```json\n{\n  \"stigmem\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/stigmem/adapters/mcp/dist/server.js\"],\n    \"env\": {\n      \"STIGMEM_URL\": \"http://localhost:8765\",\n      \"STIGMEM_API_KEY\": \"sk-your-key-here\",\n      \"STIGMEM_SESSION_ID\": \"mcp:agent-01\"\n    }\n  }\n}\n```\n\n### Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `STIGMEM_URL` | yes | — | Base URL of your Stigmem node |\n| `STIGMEM_API_KEY` | no | — | API key if the node requires auth |\n| `STIGMEM_SESSION_ID` | no | generated per call | Optional stable session id override propagated as `Stigmem-Session` for reads and writes |\n| `STIGMEM_POLL_LIMIT` | no | `50` | Facts per `subscribe_scope` call |\n\n## Security Model\n\nThe Stigmem MCP server is an editor-launched stdio subprocess. Its security\nmodel assumes:\n\n1. The host has already authorized the subprocess launch.\n2. `STIGMEM_API_KEY`, read at startup, grants the subprocess its permissions on\n   the configured Stigmem node.\n3. Every MCP tool call routed to this subprocess executes under the same key.\n\nTreat the subprocess as equivalent to running `stigmem-node` CLI commands\ndirectly. Do not share one MCP subprocess across mutually untrusted projects,\noperators, or host profiles; each trust boundary should get its own subprocess\nand key.\n\nThe subprocess does not authenticate individual MCP requests beyond the host's\nlaunch authorization. Receipts and audit events record the node identity derived\nfrom `STIGMEM_API_KEY`; pass `session_id` per call when the host can provide\nconversation-specific attribution. If no `session_id` is provided, the adapter\ngenerates one per tool call unless `STIGMEM_SESSION_ID` pins a process-level\noverride.\n\nThis is not a hostile multi-tenant boundary and not a per-conversation auth\nmechanism. Those require host-level routing to per-operator subprocesses or a\nfuture per-call identity contract.\n\n## Usage examples\n\nOnce connected, ask any MCP-aware agent:\n\n```\n# Write a decision fact\nassert_fact(\n  entity=\"decision:use-sqlite\",\n  relation=\"roadmap:status\",\n  value={\"type\":\"string\",\"v\":\"approved\"},\n  source=\"agent:cto\",\n  session_id=\"mcp:agent-01\"\n)\n\n# Query all active project constraints\nquery_facts(entity=\"project:acme-platform\", relation=\"roadmap:constraint\")\n\n# Recall context for a project question\nrecall(query=\"What is blocking the launch?\", scope=\"local\", token_budget=1000)\n\n# Poll for recent public facts\nsubscribe_scope(scope=\"public\")\n\n# Resolve a contradiction\nresolve_contradiction(\n  conflict_id=\"stigmem:conflict:abc123\",\n  winning_fact_id=\"fact-001\",\n  resolution_note=\"CTO confirmed during board review 2026-05-02\"\n)\n```\n\n## Protocol notes\n\n- `subscribe_scope` is a **single-shot poll**, not a streaming subscription. Call it\n  repeatedly with the returned `cursor` to follow new facts over time.\n- Facts are **immutable** once written. To update, assert a new fact for the same\n  `(entity, relation, scope)`. To retract, call `assert_fact` with `confidence=0.0`.\n- Scope filtering: `local` facts never leave the node. `public` facts are federatable.\n  See `Spec-02-Scopes-and-ACL` for the full scope semantics.\n- `recall` returns `content` and `instructions` arrays as separate channels, plus\n  `system_prompt_directive`. MCP hosts must keep those channels distinct and place\n  the directive above recalled content instead of concatenating recalled data into\n  higher-priority prompts.\n- `assert_fact`, `query_facts`, `recall`, and `subscribe_scope` propagate a\n  `Stigmem-Session` header. Pass `session_id` per tool call for\n  conversation-specific attribution, or set `STIGMEM_SESSION_ID` for a stable\n  process-level override.\n- `assert_fact` accepts `write_mode=\"summarize_with_provenance\"` plus\n  `derived_from=[{\"fact_id\":\"...\"}]` for legitimate agent summaries derived\n  from recalled facts.\n\n## Architecture\n\n```\nClaude Code / MCP host\n      │  MCP (stdio)\n      ▼\n@eidetic-labs/stigmem-mcp  (this package; installs the `stigmem-mcp` binary)\n      │  HTTP\n      ▼\nStigmem node  (stigmem/node)\n      │\n      ▼\n SQLite store\n```\n\nThe MCP server is stateless — it translates MCP tool calls to HTTP requests against\nthe configured Stigmem node. No local state is held in the server process.\n","readmeFilename":"README.md","_rev":"1-7dd1b999c97ad0e5422071a46d354b82"}