For agents

Enscrive gives a project a memory that outlives a session. For a coding agent that is the difference between re-deriving the same conclusion every time it opens a repository and looking it up.

The unit of memory is the project, not the user and not the conversation. enscrive project init gives the directory its own isolated tenant, and every enscrive command run anywhere inside that tree targets it automatically — with no credential in the environment, no key in the repository, and no global configuration to get wrong.

The CLI is the agent interface. There is no MCP server for the Enscrive platform today; see MCP below.

The self-teaching part

enscrive project init writes .enscrive/AGENT.md into the project. It is addressed to whatever agent works in that repository, and it teaches the loop in the agent’s own terms: how to ensure a corpus, write a memory, search it, read the scores, and retire something that stopped being true. It names that project’s tenant and endpoint.

Commit it. An agent that reads the repository finds its own instructions, which means onboarding an agent to a project’s memory requires no prompt engineering on your part.

AGENT.md is a contract, not a README. Every command it teaches must be exercised by the clean-room CI gate against a live stack — a check enforces this by extracting every enscrive … invocation from the generated document and failing if the gate does not run it. The document cannot drift into teaching something the CLI does not do.

The JSON envelope

Pass --output json to any command. Success and failure share one shape:

{
  "ok": true,
  "command": "corpus ensure",
  "data": { "id": "…", "created": true },
  "exit_code": 0
}

{
  "ok": false,
  "command": "search",
  "error": "HTTP 404: corpus not found",
  "failure_class": "FAIL_BUG",
  "exit_code": 1
}

ok and exit_code are always present. command, data, error, and failure_class are omitted when they do not apply — so data appears on success and error/failure_class on failure.

Branch on ok. Read exit_code from the envelope rather than inferring it from failure_class: the two are independent axes, and one class can map to more than one code.

Do not branch on failure_class alone. An HTTP error the server did not classify becomes FAIL_BUG regardless of what actually went wrong — the 404 above is a perfectly ordinary “you named a corpus that does not exist”, not a defect. failure_class is a reliable signal when the server sets it explicitly; otherwise error is what tells you what happened.

Without --output json, success pretty-prints the payload to stdout and failure prints [FAIL_CLASS] message to stderr.

Failure classes

The last two matter most for retry logic: FAIL_TIMEOUT means unknown outcome, not failed. Re-check state before retrying a write.

Exit codes

The loop

The commands, in the order an agent uses them. Full detail in the quickstart.

# Once per project, by a human
enscrive project init --name my-project

# Top of every session — idempotent, safe to run blind
enscrive corpus ensure --name "my-project-memory" \
  --embedding-model text-embedding-3-large --output json

# Remember
enscrive ingest documents --corpus-id <CORPUS_ID> \
  --document-id "convention/error-handling" \
  --content "Handlers return ApiError; never unwrap in a request path." \
  --output json

# Recall — always corpus-scoped
enscrive search --query "how should handlers report errors" \
  --corpus <CORPUS_ID> --limit 5 --output json

# Retire
enscrive corpus document delete --corpus-id <CORPUS_ID> \
  --document-id "convention/error-handling" --output json

Two things worth internalising:

• Always pass --corpus to search. The flag is declared optional, but a search that omits it currently fails.
• Scores are cosine similarity, not confidence. Good hits land in the 0.57–0.70 band; noise sits below 0.39. Do not discard a 0.6 as weak. Judge by the gap between the top results and the rest.

What to write

Write memories that will still be true next month: decisions and the reasons behind them, invariants, conventions, hard-won debugging conclusions, and where things live. Not transient state.

Give a memory a stable --document-id when you expect to revise it — the same id re-ingested replaces it, which makes correction a write rather than a delete-then-write. Retire memories you have proven wrong in the same session you disproved them; a stale memory is worse than no memory.

Endpoint-to-command map

v1-surface-contract.toml in the public CLI repository maps every /v1 HTTP endpoint to the CLI command that fronts it:

github.com/enscrive/enscrive-cli/blob/main/v1-surface-contract.toml

[[endpoint]]
method = "POST"
path = "/v1/search"
cli_command = "search"
status = "implemented"
deployment_tier = "any-mode"
required_plan = "free"

148 endpoints are listed; 145 are implemented and 3 are explicitly deferred with a reason. A CI check in the CLI repository fails if an endpoint is added without an entry, so the map cannot quietly fall behind the API.

Use it to go from an HTTP endpoint you found in the API reference to the command that calls it, and to see which plan and deployment tier a capability needs.

For the complete flag-level surface, see the CLI reference — generated from the binary’s own --help.

MCP

No MCP server ships for the Enscrive platform today. Agents drive the CLI directly; AGENT.md self-teaches the loop, and --output json is the machine interface.

That is the whole status. We would rather say this plainly than describe something you cannot install.