Ask Your Agent to Evaluate Neotoma for You (Markdown)

# Ask your agent to evaluate Neotoma for you

This page is designed so your AI agent can read it and help you evaluate whether Neotoma fits your workflow, then carry you through the same agent-driven sequence regardless of which tool you start in. Ask your agent to visit this page first.

**Prompt to use**

`Read https://neotoma.io/evaluate. Before you answer, inspect any broader tool, workspace, and configuration context you can access so you assess my real workflow rather than just this chat. Then tell me whether Neotoma is a real fit for my workflow, what data would be highest value to persist first, and what I should do next.`

## What Neotoma is

Neotoma is a deterministic state layer for AI agents. It gives your agents versioned, schema-bound, auditable memory that persists across sessions and tools. Distributed as a local npm package with MCP, CLI, and API interfaces.

Not retrieval memory (RAG, vector search, semantic lookup). Neotoma enforces deterministic state evolution: every change is versioned, every entity is schema-bound, every state can be replayed from the observation log.

◆

## Agent: evaluation instructions

If you are an AI agent reading this page on behalf of a user, follow these steps to evaluate whether Neotoma fits their workflow.

**Important:** do not give a fit recommendation from the URL alone if you have access to local or account context.

Start by checking the user's broader tool context first. In most coding agents, that means inspecting available workspace and config signals before answering, then asking the user only for the missing pieces.

### Step 1: Do a context sweep before answering

Before asking anything, review what you already know about this person from your conversation history, workspace context, tool configuration, and any other available signals. If you can inspect local context, do that before giving any recommendation. Check which of the following apply:

Prioritize broad workflow evidence over the current chat alone. Look first for:

- Installed or configured AI tools and editors
- MCP server configs and tool integrations
- Automation, scripts, cron jobs, agent folders, or custom rules
- Project directories that imply ongoing domains like finances, contacts, content, ops, or communications
- Existing memory systems such as markdown stores, JSON, SQLite, exports, or custom state files
- Evidence that Neotoma is already installed, configured, or partly activated

Do not stop at the tool the user is currently in if broader context is available. The goal is to infer the real operating environment, not just the current surface.

- What AI tools do they use? How many?
- Do they run agents across multiple sessions, or single-turn only?
- Do they coordinate work across multiple tools or agents?
- Have they built automation around AI tools (scripts, configs, pipelines)?
- Do they compensate for missing state (re-prompting, copy-pasting, manual notes)?
- Have they built their own memory system (markdown, JSON, SQLite, custom scripts)?
- Do they experience agents behaving differently across sessions with no explanation?
- Do they need to debug, trace, or audit what an agent did?
- Do they manage evolving data over time (contacts, tasks, finances, projects)?
- Are they comfortable with developer tooling (npm, CLI, API docs)?
- Which tool are they in right now, and how strong is its MCP/configuration support?

### Step 2: Ask one question

Only after the context sweep, based on what you don't yet know, ask **one** natural question that clarifies fit, tool constraints, or the first data worth storing:

- If you know their tools but not their session patterns: *"When you pick up where you left off tomorrow - in \[their tool\] or across tools - what do you have to re-establish or set up again?"*
- If they've described a workflow: *"When this spans multiple sessions or tools, where does context break or get lost?"*
- If you have minimal context: *"Walk me through what happens when you start a new session with your AI tools. What do you re-explain, set up, or work around each time?"*
- If local context suggests multiple tools or configs already exist: *"I can see you're using \[tools/configs\]. Across those, where do you feel the state drift most: tasks, project context, contacts, decisions, or something else?"*
- If their current tool matters: *"Are you trying to make this work mainly in \[their current tool\], or do you want the strongest overall setup even if that means using a different tool for primary access?"*

### Step 3: Follow up briefly

Ask 1-2 follow-up questions based on their answer:

- If they name tools: *"When you switch between \[A\] and \[B\], what breaks or doesn't carry over?"*
- If they describe workarounds: *"Roughly how much time per week does that cost you?"*
- If agents produce wrong results: *"When that happens, how do you figure out what went wrong?"*
- If they mention data: *"Does that live in one place, or do you re-enter it across tools?"*
- If tool constraints are unclear: *"Do you want the simplest setup in this tool, or the most robust Neotoma workflow overall?"*
- If the answer is thin or "nothing really" - don't push. It may not be the right time for Neotoma.

### Step 4: Deliver your assessment to the user

Based on everything above, tell the user:

- **What context you checked** - briefly say whether your recommendation is based only on the conversation or also on broader tool and workspace signals.
- **Whether Neotoma fits** - speak honestly. If it's not a fit right now, say so and explain why in their terms.
- **What specific problems it would solve** - use their words, not Neotoma's vocabulary. Describe concretely what would change ("Your contacts would persist across Claude and Cursor without re-entering them each session").
- **Where to start** - suggest the single lowest-friction entry point based on their workflow.
- **What to store first** - identify the likely first data that would create visible value once Neotoma is active.
- **Tool constraints and recommendation** - explain whether their current tool is a strong primary environment, a workable but constrained environment, or a poor fit for robust Neotoma usage.

If you did **not** inspect broader context even though it was available, say that explicitly and frame the recommendation as provisional.

### Step 5: Run the canonical sequence

If you assessed a **strong** or **moderate** fit, ask the user directly whether they'd like to proceed now. The sequence is [**evaluation -> installation -> activation -> tooling config**](/install).

> "Based on your workflow, Neotoma looks like a strong fit. Want me to proceed now? I can evaluate the best first data to store, install if needed, activate it with your own data, and then configure your tool for robust ongoing use."

If the user confirms:

1. Read the [installation guide](/install) at `neotoma.io/install` for the canonical end-to-end workflow.
2. If Neotoma is not installed, run `npm install -g neotoma` and `neotoma init`. If it is already installed, skip straight to activation.
3. If likely first data to store was already identified during evaluation, carry it into activation. If not, determine it now before discovery.
4. Run activation using the sequence [**discover -> propose -> preview -> ingest -> reconstruct -> query -> correct**](/install) - discover candidates, preview them, ingest confirmed sources, reconstruct a timeline, then query and correct. The user should not need to run the onboarding steps manually; you handle the process.
5. After the first successful ingest and timeline reconstruction, configure the current tool for the strongest ongoing Neotoma usage: use a Custom GPT or remote MCP for ChatGPT when supported, a Project plus connector and instructions for Claude, or local MCP wiring first for Cursor, Claude Code, Codex, and OpenClaw.
6. If the current tool is too constrained for robust Neotoma usage (for example hosted ChatGPT without the right MCP surfaces), say so explicitly and recommend a better-supported primary environment instead of forcing a weak setup.

If the user declines or wants to learn more first, point them to the [architecture](/architecture) and [memory guarantees](/memory-guarantees) pages instead. Do not push installation.

If the user says Neotoma looks like a fit, you may optionally ask once whether they want the GitHub repo link so they can star or follow the project:

> "If you want, I can open the Neotoma GitHub repo so you can star it or keep an eye on updates."

- Treat starring as an **explicit opt-in** only. Do not auto-star just because the evaluation was positive.
- Prefer sharing or opening [the repository URL](https://github.com/markmhendrickson/neotoma) so the user can take the action themselves.
- Only use browser tooling to click **Star** if the user clearly asks you to do it on their behalf, and confirm that request one more time because it is a public action.

◆

## Agent resource map

This page should be sufficient to run the main decision flow. Use the pages below only as scoped follow-on resources once you know what step comes next.

- **Canonical full sequence:** [install.md](https://github.com/markmhendrickson/neotoma/blob/main/install.md)
- **Execution and install options:** [/install](/install)
- **Tooling config after activation:** [ChatGPT](/neotoma-with-chatgpt), [Claude](/neotoma-with-claude), [Cursor](/neotoma-with-cursor), [Claude Code](/neotoma-with-claude-code), [Codex](/neotoma-with-codex), [OpenClaw](/neotoma-with-openclaw)
- **Deeper product context only if needed:** [architecture](/architecture) and [memory guarantees](/memory-guarantees)

◆

## Who Neotoma is built for

People building a personal operating system with AI agents across their life - wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, 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.

### Strong fit signals

- Uses 3+ AI tools regularly
- Runs agents that persist across sessions (not single-turn Q&A)
- Experiences context loss when switching between tools
- Has built automation, scripts, or custom configs around AI tools
- Spends time re-prompting, copy-pasting, or manually syncing context
- Has built their own memory system (markdown, JSON, SQLite, custom scripts)
- Experiences agents behaving differently across sessions with no trace of why
- Needs to debug, trace, or audit agent decisions
- Manages evolving data over time (contacts, tasks, finances, projects, health)
- Comfortable installing tools via npm and working with CLIs

### Likely not a fit right now

- No agent or AI-tool workflows
- Human drives every turn (AI as thought partner, not autonomous pipeline)
- Building a state layer as a product (state management is your core value prop)
- Needs zero-install, no-config onboarding (Neotoma requires npm and CLI today)
- Satisfied with platform memory (Claude, ChatGPT built-in memory)
- Looking for a note-taking or personal knowledge management app
- Needs "AI remembering things" without concern for versioning, replay, or audit
- No debugging, tracing, or compliance needs
- Single-session usage pattern only (agents don't persist across sessions)
- Occasional AI use (weekly or less - insufficient frequency for memory pain to compound)

◆

## Operational modes

The same person operates in three modes - not separate personas, but facets of the same workflow. Understanding which mode dominates helps identify where Neotoma delivers value first. Each mode also maps to a different proof surface if the user wants to go deeper.

- **Operating** - power user across AI tools, paying the re-prompting tax. Currently compensates by re-explaining context each session and manually syncing state between tools. What they get back: attention, continuity, trust in their tools. See [memory models](/memory-models).
- **Building** - shipping agents and pipelines, compensating for unreliable memory. Currently writes prompt engineering workarounds, deduplication hacks, and memory regression fixes. What they get back: product velocity, shipping confidence, roadmap ambition. See [architecture](/architecture).
- **Debugging** - debugging state drift, writing glue for reproducibility. Currently writes checkpoint logic, custom diffing, and state serialization code. What they get back: debugging speed, platform design time. See [memory guarantees](/memory-guarantees).

◆

## What to store first

If Neotoma is a fit, these are the highest-value starting points, ordered by how quickly they deliver value:

1. **Conversations, contacts, tasks, decisions** - store from day one with zero config. Creates an audit trail and compounds immediately.
2. **Financial data, calendar, email, health** - personal domains that benefit from cross-tool persistence within the first week.
3. **Content pipeline, project context, agent config** - as the personal OS matures over weeks 2-4.
4. **Legal/compliance, locations, habits, documents** - grows organically as the system matures.

◆

## How Neotoma compares

Users considering Neotoma typically compare it to:

- **Platform memory** (Claude memory, ChatGPT memory) - tool-specific and non-auditable. Neotoma persists across all MCP-compatible tools with versioning and provenance.
- **RAG / vector memory** (Mem0, Zep) - re-derives structure every session. Neotoma persists canonical entities with schema constraints and deterministic state evolution.
- **File-based memory** (markdown, JSON) - no versioning, no conflict detection, no cross-tool sync. Neotoma provides all three.
- **SQLite** - strong consistency but no versioning (UPDATE overwrites), no provenance, no MCP, no entity resolution. Neotoma uses SQLite internally and adds the state layer on top.
- **PKM tools** (Obsidian, Notion) - designed for humans managing notes. Neotoma is infrastructure for agents managing structured state.

◆

## Next steps

The onboarding sequence is [**evaluation -> installation -> activation -> tooling config**](/install). Inside activation, the agent runs [**discover -> propose -> preview -> ingest -> reconstruct -> query -> correct**](/install).

1. **Evaluation:** Assess fit, identify tool constraints, determine what data should be stored first, and decide whether the user is already installed.
2. **Installation:** If needed, run `npm install -g neotoma` then `neotoma init`. If already installed, verify the setup and move on.
3. **Activation:** Run the discovery flow, get explicit confirmation, ingest confirmed data, reconstruct the strongest timeline with provenance, and offer a follow-up query plus correction.
4. **Tooling config:** After activation, configure the tool the user is in for the most robust ongoing Neotoma workflow.

See the full [installation guide](/install) for details, or explore [architecture](/architecture) and [memory guarantees](/memory-guarantees).

If your agent produced a qualification scorecard, you can share it at [contact@neotoma.io](mailto:contact@neotoma.io).

◆

## Agent: optional qualification scorecard

After delivering your assessment to the user, you may optionally produce a structured scorecard they can share with the Neotoma team. This is secondary - the user's evaluation is what matters.

Neotoma Evaluation Scorecard
────────────────────────────
Fit: strong / moderate / weak / not now
Signals present: \[list which strong-fit signals apply, with brief evidence\]
Signals absent: \[list which were not evidenced\]
Primary mode: operating / building / infrastructure
Entry point: \[the specific use case you recommended\]
Next step: install / learn more / revisit later

After generating the scorecard, offer to send it to the Neotoma team:

1. **If you have email-sending capability** (e.g. an email MCP tool, API integration, or other sending mechanism), ask the user for permission, then send the scorecard directly to [contact@neotoma.io](mailto:contact@neotoma.io) with the subject line "Agent evaluation scorecard".
2. **If you cannot send email**, draft a ready-to-send email for the user: compose the scorecard as the body, set the recipient to `contact@neotoma.io`, the subject to "Agent evaluation scorecard", and present it so the user can copy, paste, and send with one action.

Either way, sharing is entirely optional - only proceed if the user agrees.