Walkthrough (Markdown)

# Walkthrough

You use Claude, Cursor, and ChatGPT throughout the day. By the third tool switch, you're re-explaining who your contacts are, what you decided last session, and which tasks are still open. This walkthrough shows what changes when a shared state layer sits behind all of them, and how that same system pays off across operating, building integrations, and debugging.

In day-to-day use, your **AI agent** issues these MCP tool calls (or the equivalent [CLI](/cli) commands) as part of the conversation-you are not expected to paste raw payloads yourself. Scripts, integrations, and power users can also call the same operations directly via CLI or [REST API](/api).

Every example below shows MCP `store` and `retrieve` (except the audit, which uses CLI). Each is preceded by the kind of chat message that typically leads the agent to run it.

Operating

Sessions 1 and 3 show the user-facing outcome: context survives tool switches, and later updates become the new state instead of another re-prompting burden.

Building

Building means the integration surface: the MCP and CLI contract that lets agents, scripts, and other tools talk to the same state layer.

Debugging

The audit trail is what makes the system inspectable later: you can trace what changed, when it changed, and which tool authored it.

◆

## Operating: A conversation produces durable state[#](#session-1)

1OperatingCursorYou're planning a freelance project with your agent. The conversation mentions a client, a rate, and a task. Instead of losing this when the session ends, the agent stores it.

Chat that triggers this

> “We're doing a freelance data-pipeline project with Sarah Chen at Lattice Health. She's VP Eng, the rate is $180/hr, and I need to send her the SOW by tomorrow.”

MCP store call

store({ entities: \[ { entity\_type: "contact", name: "Sarah Chen", company: "Lattice Health", role: "VP Engineering", context: "Freelance data-pipeline project" }, { entity\_type: "task", title: "Send SOW to Sarah Chen", status: "pending", due\_date: "2025-04-02", rate: "$180/hr" } \], relationships: \[ { relationship\_type: "REFERS\_TO", source\_index: 1, target\_index: 0 } \], idempotency\_key: "cursor-session-sarah-sow-1710268800" })

Response

{ entities: \[ { entity\_id: "ent\_a7c3f1e209b4d8...", entity\_type: "contact", observation\_id: "obs\_91a0e3cf..." }, { entity\_id: "ent\_d42b8e5f17c6a3...", entity\_type: "task", observation\_id: "obs\_5f28c4d1..." } \] }

The contact and task are now versioned entities with provenance - who stored them, when, and from which session. The task links to the contact it references. This is the data your agent would normally lose at the end of the context window.

◆

## Building: Another tool integrates with the same state layer[#](#session-2)

2BuildingClaudeNext morning, you open Claude to draft the SOW. Instead of re-explaining who Sarah is and what the project covers, the agent retrieves what it already knows. This is the building surface in practice: Claude is integrating against the same store and retrieve contract as the earlier Cursor session.

Chat that triggers this

> “Draft an SOW for Sarah Chen at Lattice Health for the same freelance data-pipeline project. Use the details we already have on her and the engagement.”

MCP retrieve call

retrieve\_entity\_by\_identifier({ identifier: "Sarah Chen" })

Response

{ entity\_id: "ent\_a7c3f1e209b4d8...", entity\_type: "contact", snapshot: { name: "Sarah Chen", company: "Lattice Health", role: "VP Engineering", context: "Freelance data-pipeline project" }, observation\_count: 1, last\_observation\_at: "2025-03-31T14:22:00Z" }

The agent drafts the SOW and records the completed task with a note on what was sent.

Chat that triggers this

> “I sent the SOW: 40 hours, $180/hr, starting April 7. Mark the 'send SOW to Sarah' task done and note what went out.”

Update the task

store({ entities: \[ { entity\_type: "task", title: "Send SOW to Sarah Chen", status: "completed", completed\_at: "2025-04-01T09:15:00Z", note: "SOW sent via email - 40hr engagement, $180/hr, starts Apr 7" } \], idempotency\_key: "claude-session-sow-sent-1710355200" })

The task entity now has two observations: the original from Cursor (pending) and the update from Claude (completed). Both are preserved. No re-prompting was needed - Claude had the same state Cursor stored.

◆

## Operating: Shared state stays current across later tool switches[#](#session-3)

3OperatingChatGPTA week later, Sarah emails to say the project scope changed. You discuss it in ChatGPT. The agent stores the updated contact, but Neotoma doesn't silently overwrite the previous version - it appends a new observation.

Chat that triggers this

> “Sarah wants to expand scope to include a monitoring dashboard, and the rate is now $195/hr.”

Updated store

store({ entities: \[ { entity\_type: "contact", name: "Sarah Chen", company: "Lattice Health", role: "VP Engineering", context: "Scope expanded: data pipeline + monitoring dashboard", rate: "$195/hr" } \], idempotency\_key: "chatgpt-session-sarah-scope-1711046400" })

Later, back in Cursor, you ask: "What's the latest on the Lattice Health project?" The agent retrieves the current snapshot and sees the full history.

Chat that triggers this

> “What's the latest on the Lattice Health project with Sarah Chen? Show the current details and what changed.”

Retrieve with history

retrieve\_entity\_by\_identifier({ identifier: "Sarah Chen" })

Response

{ entity\_id: "ent\_a7c3f1e209b4d8...", entity\_type: "contact", snapshot: { name: "Sarah Chen", company: "Lattice Health", role: "VP Engineering", context: "Scope expanded: data pipeline + monitoring dashboard", rate: "$195/hr" }, observation\_count: 2, last\_observation\_at: "2025-04-07T11:30:00Z" }

The snapshot reflects the latest state. The original observation is preserved, so you can trace what changed - the scope expanded from "data pipeline" to "data pipeline + monitoring dashboard" and the rate went from $180 to $195.

◆

## Debugging: Trace who changed what and when[#](#audit)

4DebuggingWhen something looks wrong - or you just want to know the history - inspect the full observation trail.

You or your agent can run this from a terminal when you want a raw log-most of the time the agent surfaces the same history inside chat.

CLI inspect

$ neotoma observations list --entity-id ent\_a7c3f1e209b4d8... OBSERVATION\_ID CREATED\_AT SOURCE obs\_91a0e3cf... 2025-03-31T14:22:00Z agent:cursor-session-4f2a context: Freelance data-pipeline project rate: (not set) obs\_c8e6b2f4... 2025-04-07T11:30:00Z agent:chatgpt-session-7d1b context: Scope expanded: data pipeline + monitoring dashboard rate: $195/hr

Every field traces to a source, a timestamp, and the tool that authored it. Across three tools and multiple sessions, you have one consistent record with a full trail.

◆

## What changes[#](#what-changes)

Before: you are the sync layer

- ×Re-explain contacts, rates, and project context every session
- ×Copy-paste between Claude, Cursor, and ChatGPT to keep them in sync
- ×Discover a fact silently changed and have no way to trace why
- ×Maintain markdown notes as a manual workaround for agent amnesia

After: a shared state layer handles it

- →Contacts, tasks, and decisions persist across tools and sessions
- →Any tool retrieves the same state - no re-prompting
- →Changes append versioned observations - nothing is silently overwritten
- →Every field traces to a source, timestamp, and authoring tool

◆

## Guarantees in action[#](#guarantees)

- →**Cross-tool continuity.** Cursor, Claude, and ChatGPT share the same state layer. Store once, retrieve anywhere.
- →**Cross-session persistence.** Context survives session boundaries. No context window means no re-prompting.
- →**No silent mutation.** Every change appends a versioned observation. You always know what the previous state was.
- →**Full provenance.** Every observation records who authored it, when, and from which tool and session.
- →**Relationship graph.** Entities link to each other. Tasks connect to the contacts and decisions they reference.
- →**Replayable history.** The observation log reconstructs any past state. Debug by replaying, not by guessing.

◆

## Go deeper[#](#go-deeper)

- [Install](/install) — get started in under a minute
- [Architecture](/architecture) — state flow, guarantees, and how data enters Neotoma
- [MCP reference](/mcp) — full action catalog for agents
- [Memory guarantees](/memory-guarantees) — the six guarantees every operation upholds
- [Entity types](/types/contacts) — contacts, tasks, transactions, and more