neotoma 0.12.1 → 0.14.0

package/README.md

@@ -2,7 +2,7 @@
 
 Your agents forget. Neotoma makes them remember.
 
-Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, OpenClaw, IronClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
+Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, Windsurf, VS Code, Continue, Letta, OpenClaw, IronClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
 
 **[neotoma.io](https://neotoma.io)** · **[Evaluate](https://neotoma.io/evaluate)** · **[Install](https://neotoma.io/install)** · **[Documentation](https://neotoma.io/docs)**
 
@@ -53,7 +53,9 @@ graph LR
 | **Privacy-first**           | Your data stays local. Never used for training. Nothing is stored unless you approve it; no background scanning or implicit captures. Full export and deletion control. |
 | **Deterministic**           | Same input always produces same output. Schema-first extraction, hash-based entity IDs, full provenance. No silent mutation.                                |
 | **Immutable and verifiable** | Append-only observations; history cannot be rewritten. Hash-based entity IDs are tamper-evident. Full provenance chain from any state to its source.       |
-| **Cross-platform**          | One memory graph across Claude, ChatGPT, Cursor, OpenClaw, IronClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
+| **Cross-platform**          | One memory graph across Claude, ChatGPT, Cursor, Windsurf, VS Code, Continue, Letta, OpenClaw, IronClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
+
+Full compatibility matrix: [Integrations](docs/integrations/matrix.md).
 
 ## State guarantees
 
@@ -146,14 +148,14 @@ Three interfaces. One state invariant. Every interface provides the same determi
 | Interface      | Description                                                                                                                    |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | **REST API**   | Full HTTP interface for application integration. Entities, relationships, observations, schema, timeline, and version history. |
-| **MCP Server** | Model Context Protocol for Claude, ChatGPT, Cursor, OpenClaw, IronClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
+| **MCP Server** | Model Context Protocol for Claude, ChatGPT, Cursor, Windsurf, VS Code, Continue, Letta, OpenClaw, IronClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
 | **CLI**        | Command-line for scripting and direct access. Inspect entities, replay timelines, and manage state from the terminal.          |
 
 All three map to the same OpenAPI-backed operations. MCP tool calls log the equivalent CLI invocation.
 
 ## Who this is for
 
-People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, IronClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
+People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, Windsurf, VS Code, Letta, OpenClaw, IronClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
 
 | Mode | What you're doing | The tax you pay without Neotoma | What you get back |
 | ---- | ----------------- | ------------------------------- | ----------------- |
@@ -242,7 +244,25 @@ npm test
 
 Neotoma exposes state via MCP. Local storage only in preview. Local built-in auth.
 
-**Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenCode](docs/integrations/hooks/opencode.md) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw) · [IronClaw](https://neotoma.io/neotoma-with-ironclaw)
+**Full compatibility matrix:** [Integrations](docs/integrations/matrix.md) · [neotoma.io/integrations](https://neotoma.io/integrations)
+
+| Host | Modes | Install | Setup guide |
+| --- | --- | --- | --- |
+| Cursor | MCP + hooks | `neotoma setup --tool cursor --yes` | [neotoma-with-cursor](https://neotoma.io/neotoma-with-cursor) |
+| Claude Code | MCP + hooks | `neotoma setup --tool claude-code --yes` | [neotoma-with-claude-code](https://neotoma.io/neotoma-with-claude-code) |
+| Claude Desktop | MCP (local + remote) | `neotoma setup --tool claude-desktop --yes` | [neotoma-with-claude](https://neotoma.io/neotoma-with-claude) |
+| Claude Agent SDK | hooks | adapter install | [hooks/claude_agent_sdk.md](docs/integrations/hooks/claude_agent_sdk.md) |
+| ChatGPT | MCP App + Custom GPT Actions | Manual HTTPS + OAuth | [neotoma-with-chatgpt](https://neotoma.io/neotoma-with-chatgpt) |
+| Codex CLI | MCP + hooks | `neotoma setup --tool codex --yes` | [neotoma-with-codex](https://neotoma.io/neotoma-with-codex) |
+| OpenClaw | Native plugin + MCP | `neotoma setup --tool openclaw --yes` | [neotoma-with-openclaw](https://neotoma.io/neotoma-with-openclaw) |
+| IronClaw | MCP | `neotoma setup --tool ironclaw --yes` | [neotoma-with-ironclaw](https://neotoma.io/neotoma-with-ironclaw) |
+| OpenCode | hooks | plugin install | [hooks/opencode.md](docs/integrations/hooks/opencode.md) |
+| Windsurf | MCP | `neotoma setup --tool windsurf --yes` | [neotoma-with-windsurf](https://neotoma.io/neotoma-with-windsurf) |
+| Continue | MCP | `neotoma setup --tool continue --yes` | [neotoma-with-continue](https://neotoma.io/neotoma-with-continue) |
+| VS Code (Copilot Chat) | MCP | `neotoma setup --tool vscode --yes` | [neotoma-with-vscode](https://neotoma.io/neotoma-with-vscode) |
+| Letta | MCP (streamable HTTP, SSE, stdio) | Manual SDK setup | [neotoma-with-letta](https://neotoma.io/neotoma-with-letta) |
+
+Shared client libraries: [`@neotoma/client`](packages/client) (TypeScript), [`neotoma-client`](packages/client-python) (Python). Not yet supported: LangGraph, CrewAI — see [Integrations roadmap](docs/integrations/matrix.md#not-yet-supported-roadmap).
 
 For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh`) or signed shim (`scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh`) instead of pointing installed MCP clients at a `tsx watch` stdio process. `neotoma mcp config` defaults to **`b`** for low-friction local stdio setup; use **`a`** for signed + AAuth HTTP `/mcp` proxy entries when the Neotoma API is running, **`c`** for direct stdio, or **`d`** when both MCP entries should target prod.
 
@@ -250,19 +270,9 @@ For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_st
 
 **Representative actions:** `store`, `retrieve_entities`, `retrieve_entity_snapshot`, `merge_entities`, `list_observations`, `create_relationship`, `list_relationships`, `list_timeline_events`, `retrieve_graph_neighborhood`. Full list: [MCP spec](docs/specs/MCP_SPEC.md).
 
-## Using with AI tools (hooks)
-
-Neotoma also integrates into harnesses that expose lifecycle hooks. Hooks and MCP compose: hooks are the reliability floor (guaranteed capture, retrieval injection, compaction awareness, persistence safety net) and MCP remains the quality ceiling (agent-driven structured writes).
-
-| Harness | Package | Guide |
-| --- | --- | --- |
-| Claude Code | [`packages/claude-code-plugin`](packages/claude-code-plugin) | [docs/integrations/hooks/claude_code.md](docs/integrations/hooks/claude_code.md) |
-| Cursor | [`packages/cursor-hooks`](packages/cursor-hooks) | [docs/integrations/hooks/cursor.md](docs/integrations/hooks/cursor.md) |
-| OpenCode | [`packages/opencode-plugin`](packages/opencode-plugin) | [docs/integrations/hooks/opencode.md](docs/integrations/hooks/opencode.md) |
-| Codex CLI | [`packages/codex-hooks`](packages/codex-hooks) | [docs/integrations/hooks/codex_cli.md](docs/integrations/hooks/codex_cli.md) |
-| Claude Agent SDK | [`packages/claude-agent-sdk-adapter`](packages/claude-agent-sdk-adapter) | [docs/integrations/hooks/claude_agent_sdk.md](docs/integrations/hooks/claude_agent_sdk.md) |
+### Hooks composition
 
-Shared client libraries: [`@neotoma/client`](packages/client) (TypeScript), [`neotoma-client`](packages/client-python) (Python).
+Hooks integrate with harnesses that expose lifecycle events. Hooks and MCP compose: hooks are the reliability floor (guaranteed capture, retrieval injection, compaction awareness, persistence safety net), and MCP remains the quality ceiling (agent-driven structured writes). Per-harness hooks packages: [`claude-code-plugin`](packages/claude-code-plugin), [`cursor-hooks`](packages/cursor-hooks), [`opencode-plugin`](packages/opencode-plugin), [`codex-hooks`](packages/codex-hooks), [`claude-agent-sdk-adapter`](packages/claude-agent-sdk-adapter). Per-harness setup guides in [`docs/integrations/hooks/`](docs/integrations/hooks/).
 
 ### OpenClaw native plugin
 

package/dist/actions.d.ts

@@ -3,12 +3,36 @@ import { type GuestIdentity } from "./services/access_policy.js";
 import { type AgentIdentity } from "./crypto/agent_identity.js";
 import { type StoreInterpretationInput } from "./shared/action_schemas.js";
 export declare const app: import("express-serve-static-core").Express;
+/**
+ * Returns true when the given IP is within the configured NEOTOMA_TRUSTED_PROXY_IPS.
+ * Supports exact IPv4 match, IPv4 /8–/32 CIDR notation, and ::ffff:<ipv4> mapped addresses.
+ * When NEOTOMA_TRUSTED_PROXY_IPS is not set this always returns false.
+ */
+export declare function isTrustedProxyIP(ip: string, env?: NodeJS.ProcessEnv): boolean;
 /**
  * True when the request is genuinely local to this process.
  *
  * SECURITY: a same-host reverse proxy (Caddy, nginx, Cloudflare tunnel, etc.)
  * connects to Node over loopback even for public internet callers. In
  * production, loopback alone is therefore not enough to grant local-dev auth.
+ *
+ * NEOTOMA_TRUSTED_PROXY_IPS: comma-separated list of IPs or IPv4 CIDRs whose
+ * XFF entries are trusted and do not disqualify a loopback-socket request from
+ * being considered local. Use this for tunnel setups where cloudflared (or
+ * similar) injects a non-loopback XFF entry that represents a controlled
+ * internal hop, not a public internet caller.
+ *
+ * The XFF IP that cloudflared injects depends on its forwarding mode:
+ * - Warp / CGNAT mode: typically 100.64.x.x (CGNAT range, NEOTOMA_TRUSTED_PROXY_IPS=100.64.0.0/10)
+ * - Passthrough mode: the upstream client IP (Vercel egress, CDN edge, etc.)
+ *
+ * To find the actual IP: start the server, make a request through the tunnel,
+ * and check Neotoma stderr for "isLocalRequest rejected: XFF contains <ip>".
+ * Set NEOTOMA_TRUSTED_PROXY_IPS to that IP or its enclosing CIDR.
+ *
+ * NEOTOMA_TRUSTED_PROXY_IPS and NEOTOMA_TRUST_PROD_LOOPBACK=1 are independent
+ * and can coexist. NEOTOMA_TRUST_PROD_LOOPBACK=1 bypasses the XFF check
+ * entirely and remains valid for single-host deployments without a tunnel.
  */
 export declare function isLocalRequest(req: express.Request): boolean;
 /**
@@ -88,6 +112,13 @@ export declare function storeStructuredForApi(params: {
         observation_id: string;
     }[];
 } | {
+    store_warnings?: {
+        code: string;
+        message: string;
+        observation_index: number;
+        entity_type: string;
+        entity_id: string;
+    }[] | undefined;
     warnings?: {
         code: string;
         policy: string;

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}