NeuralMind Local API (/v1) — Technical Spec

Status: DRAFT for review Date: 2026-10-02. Revised the same day with the mem0 gap analysis (§4.1–§4.4) and the PR 1 additions it produced. Baseline: v4.3.5 (main @ 39617aa). Every file:line below was checked against that commit. Companions:

• LOCAL-API-PR1-SCOPE.md: the first PR, scoped to files, routes, tests and docs.
• LOCAL-API-PR1-SESSION-PROMPT.md: a ready-to-paste prompt for the session that implements PR 1.

Related: PERFORMANCE-FUTURE-PROOFING-SPEC.md §5 and PERFORMANCE-FUTURE-PROOFING-PLAN.md Phase 2. They cover the same daemon from the latency side. §9 lists where the two programmes touch.

Scope note. CLAUDE.md routes BRD/TRD strategy documents to the private neuralmind-marketing repo. This is an engineering spec that cites file:line in this repo, like the performance spec next to it, so it lives in docs/specs/. Move it if you prefer.

0. Summary

The question: should NeuralMind offer an API “like mem0, that is free”?

The answer this spec implements: copy mem0’s developer experience, but not its hosting model. Concretely:

• One documented, versioned HTTP contract (/v1).
• It is served by the process users already run: the daemon.
• A stdlib Python client with mem0-shaped verbs.
• A Docker image a team runs on its own infrastructure.

Cheval-Volant LLC hosts nothing. The README’s statement that NeuralMind “transmits no repository content off your machine” (README.md:67) stays true by construction:

• The default bind is loopback.
• Binding to other interfaces is a separate, opt-in server mode.
• In server mode, projects are allowlisted and every caller authenticates with a per-user token.

Why not a hosted API. This was assessed in the conversation that produced this spec; the reasons are recorded here so they aren’t re-litigated:

1. Positioning. “Local-first, no telemetry” is the headline (README.md:10,16,67), and “Hosted SaaS” is an explicit non-goal (ROADMAP.md:212).
2. Unit cost. The free tier costs Cheval-Volant nothing per user today (commercial-terms.json → pricing.free). A hosted free tier would mean per-repository index compute and storage, plus custody of customers’ source code.
3. The hot path is local. Hooks run on every tool call and the watcher reads the working tree. A remote API adds a network hop to that path and still needs a local install.
4. Pricing model. NeuralMind prices seats ($29/user/mo Team); a mem0-style API prices operations. A hosted API is also, in practice, the “real-time cross-machine sync” that commercial-terms.json → do_not_market says not to market.

What mem0 ships, for parity reference:

What NeuralMind takes from mem0:

• The interface: the verbs, one documented contract, a generated OpenAPI document, auth on by default, and a one-command Docker server.
• Memory capabilities that need no LLM (§4.1): meaning-based search over decisions, a real per-record change history, duplicate hints on add, relevance scores, richer filters, review-by dates, agent and session attribution, batch and export, usefulness feedback, and framework adapters.

What it leaves out:

• An LLM in the write path.
• External databases; the stores stay in SQLite under .neuralmind/.
• A hosted tier.

1. What exists today

1.1 Problems this spec fixes

A1. There is no versioned public contract, and every surface returns a different search shape:

• Daemon /search returns raw backend hits: {id, document, metadata, distance, score}.
• MCP neuralmind_search returns {id, label, file_type, source_file, score} (mcp_server.py:153-169).
• The UI’s /api/search returns {id, label, source_file, community, score} (server.py:75-94).

A2. Projects are addressed by any filesystem path the request supplies (daemon.py:363-394):

• No allowlist of project roots exists anywhere. core.validate_project and paths.py only keep artifact subpaths inside the root they are given.
• As a result, POST /validate {"write": true} writes .neuralmind/ files into any directory the daemon user can write (core.py:76-126).

A3. The network posture is unguarded:

• --host accepts any address, so the result is plaintext HTTP and indexing of whatever path the request names, protected only by the token.
• There is no Host-header check.
• There is no request-body cap (daemon.py:532-535).
• The token is accepted in the URL query string (daemon.py:515), which leaks into logs and shell history.

A4. Errors have no code. Every error is {"error": "<text>"}, and a 500 returns the exception’s class and message (daemon.py:402-403).

A5. Nothing can be written over HTTP. Decisions, feedback, file activity and document ingest are reachable only through MCP or the CLI.

A6. Ports collide:

• The daemon and serve both default to 8787 (perf spec finding H5).
• 8765 is claimed by four things: the systemd/launchd serve templates (scripts/systemd/neuralmind-serve.service, scripts/launchd/com.neuralmind.serve.plist), scripts/install-team.sh:47, the MCP-over-HTTP stub, and SelfHostedConfig.

A7. Docker does not run a server:

• docker-compose.yml has no command:, and the image CMD is neuralmind --help (Dockerfile:66-67), so the container exits and restart: unless-stopped restarts it in a loop.
• The license is mounted at /app/license.json, but NEURALMIND_LICENSE_PATH is never set, so the default path doesn’t find it.
• The Dockerfile has no HEALTHCHECK and no VOLUME.

A8. MCP RBAC is self-asserted:

• The caller supplies actor and role (mcp_server.py:1321-1322).
• The config-driven mcp_security.get_security_manager is never called; mcp_server.py:76-81 builds a manager with default settings instead.
• Over stdio this is harmless, because the caller is the local user. Over any network transport it would make the RBAC meaningless.

A9. The HTTP contract has no documentation. CLI-Reference.md:2287-2338 documents the daemon command, not what it serves.

2. Goals and non-goals

Goals

Non-goals

3. Design principles

P1. One dispatch core, many transports. This is already the stated intent of the daemon (daemon.py:338-344, PRD 5 FR3). /v1 adds a declarative route table on top, and the legacy unversioned routes call the same handler functions, so behaviour cannot drift between them.

P2. Loopback is the default; remote access is a mode. Server mode is switched on explicitly (--allow-remote), and switching it on changes three things together:

• Projects come from an allowlist; they cannot be registered over HTTP.
• Tokens are per user and carry a role.
• TLS is required, unless the operator passes an explicit --insecure-http acknowledgement for a TLS-terminating proxy.

P3. Identity comes from credentials, never from the request body. This is the opposite of A8.

P4. Handlers call cores and stores, not the tool_* wrappers.

• mcp_server.get_mind keeps its own _mind_cache, so calling tool_* from the daemon would load each project twice.
• Normalisers that both MCP and REST need (search-hit shape, compact memory row) move into one shared module that both import.

P5. License boundary: everything in this spec is MIT core.

• neuralmind/tier2/ may configure or extend the API (seat checks, the hash-chained audit, SelfHostedConfig) by importing core.
• Core never imports neuralmind/tier2/.
• So the reserved-path guard in tier2/self_hosted.py:33-113 is re-implemented in core, not imported.

P6. Changes within v1 are additive.

• New routes and response fields are allowed.
• Removing or renaming anything requires /v2.
• Clients must ignore response fields they don’t recognise; servers ignore request fields they don’t recognise.

P7. Side effects are documented per route. Some reads also learn. For example, query reinforces synapses through reinforce_from_query (synapse_feedback.py:229, called from mind.query()). The reference states this for every route where it happens.

4. Resource model and the mem0 mapping

Project ids.

• In loopback mode the id is p_ followed by the first 12 hex characters of sha256(realpath(root)). It is deterministic and stable across daemon restarts.
• In server mode an operator may assign readable aliases (--project api=/srv/repos/api gives id api).
• Ids match ^[a-z0-9][a-z0-9_-]{0,63}$.
• Clients treat ids as opaque.

mem0 → NeuralMind

4.1 What else to borrow from mem0: gap analysis

The table above covers mem0’s interface. This section covers its memory features, each checked against our store on 39617aa. Every item here works without an LLM and makes no network calls.

4.2 PR M: memory upgrades (design)

PR M is independent of server mode. It needs PR 1’s /v1 routing and can land before or after PR 2.

Schema migration from v1 to v2. SCHEMA_VERSION is at store.py:115; the migration runs in _init_schema (store.py:299-331).

• ALTER TABLE decisions ADD COLUMN for agent TEXT, session_id TEXT and review_by TEXT (an ISO date).
  • Append only; never reorder. _row_to_record maps columns by position (store.py:190-212), and every explicit SELECT lists them (for example store.py:750-758). Each read path gains the three columns at the end.
• decision_events(id INTEGER PRIMARY KEY, decision_id TEXT, at TEXT, kind TEXT, actor TEXT, changes TEXT, note TEXT). changes is JSON {field: [old, new]}. Indexed on (decision_id, at).
• decision_vectors(decision_id TEXT PRIMARY KEY, model_id TEXT, dim INTEGER, vector BLOB, content_sha TEXT). vector is float32.
• FTS rebuild. decisions_fts and its three triggers (store.py:147-171) gain evidence and tags. The wiki and the MCP tool descriptions now say search covers titles and rationales only (§12 item 7). tests/memory/test_search_scope_docs.py compares them with the FTS columns, so it fails until this PR updates them to name evidence and tags.
• Safety. The migration is idempotent and tested from a v1 database fixture. Records written by v1 code keep working, with the new columns NULL.

History.

• Every store write appends an event in the same transaction:

  Store call	Event
  record	created
  update	amended, with a field-by-field diff
  update_status	stale or active
  invalidate	invalidated, with the reason (which today only lands in evidence)
  restore	restored
  feedback	feedback

• actor comes from the token in server mode, and from author or agent otherwise.
• GET …/memories/{mid}/history returns events oldest first, paginated.
• A hard delete removes the record but keeps its events, flagged deleted, so the audit trail survives. tier2’s hash-chained audit can consume the same events.

Semantic search. Shipped in v4.8.0 on its own, ahead of the rest of PR M (no schema v2 migration, no decision_events, no FTS rebuild). It differs from the design below in four places:

• It embeds title + rationale, the fields keyword search indexes, not + evidence. invalidate, mark_stale and restore append lifecycle notes to evidence, which would re-embed on every status change and mix notes into the meaning. It also keeps the docs’ one list of searched fields true in every mode (tests/memory/test_search_scope_docs.py). Evidence joins every mode together when the FTS rebuild lands.
• Every surface embeds lazily, at search time: the first semantic or hybrid search fills missing or stale vectors in one pass. Nothing embeds at write time, the daemon included, so recording stays model-free.
• Search never downloads the model (OnnxMiniLMEmbedder.local_model_dir). Without it, hybrid returns keyword results with a notice, and semantic raises SemanticSearchUnavailableError.
• Semantic results below a cosine of 0.30 are dropped (semantic.MIN_SIMILARITY), so an unanswerable question doesn’t get the nearest decisions anyway. Hybrid uses RRF with k = 60 over pools of max(4 × limit, 20). The confidence multiplier under “Feedback” waits for G9.

The paraphrase queries, the floor and the keep rule for the default mode were committed before semantic search was run on the eval set (_paraphrase_preregistration in tests/memory/fixtures/decision_queries.json). Hybrid passed and is the default; the per-mode results and misses are in docs/wiki/Memory-Layer.md#eval-harness.

The original design:

• What gets embedded. title + rationale + evidence, using OnnxMiniLMEmbedder (onnx_embedder.py:59, 192).
• When. The daemon already has the embedder warm, so it embeds at write time. The CLI’s direct mode doesn’t embed at write time. A missing vector, or a stale one (content_sha mismatch), is filled in lazily by the next search or by a maintenance job.
• How it searches. Brute-force cosine over the project’s vectors in numpy. A repository holds hundreds to low thousands of decisions, so no approximate-nearest-neighbour index or turbovec dependency is needed. Revisit only if a measurement says otherwise.
• Hybrid ranking. mode=hybrid, the default once PR M lands, fuses the FTS and vector rankings with reciprocal rank fusion. ContextSelector._rrf_merge (context_selector.py:378) is a method, so lift a small shared rrf() function rather than importing the selector.
• Model changes. model_id is stored with each vector, so changing the model re-embeds rather than mixing vector spaces. This is the same principle as perf finding D6 and its index stamp.
• Every surface agrees. The CLI (neuralmind decisions query) and MCP (neuralmind_memory_search) gain the same modes through the store.
• The keyword half has landed. keyword mode is no longer every-word-required: the query’s words, minus stopwords, are ORed and ranked by bm25, so a question finds what its keywords find (store.py, _search_terms and _query_fts; the LIKE fallback ranks by how many words match). Hybrid fuses with that ranking.

review_by.

• A date in the past is rejected at write time with 422.
• effective_status is computed on read, so it is correct without a background job.
• A maintenance pass persists STALE and appends an event, so the PreToolUse stale guard (_stale_decision_context, hooks.py:662) sees it too.

Feedback. As described in G9. In hybrid mode, confidence acts as a mild multiplier on the score: score × (0.5 + 0.5 × confidence). A decision flagged unhelpful sinks in the results without disappearing.

Tests.

• The v1 → v2 migration from a fixture database.
• Every write path appends an event, with a correct diff.
• A delete keeps the record’s events.
• Semantic search finds a paraphrase that keyword search misses (fixture: a “WAL locking” decision found by “sqlite concurrency”). Keyword search now matches any word, so the fixture decision must contain neither “sqlite” nor “concurrency”.
• Vectors re-embed when the model or the content changes.
• review_by flips the effective status exactly at the boundary.
• Feedback stays within its bounds.

Docs.

• The Memory Layer wiki page, including fixing the evidence claim.
• The HTTP API page and the release notes.
• A use case: “Find the decision behind this code even when you don’t know its words.”

Publish no “better recall” number unless it has been measured. The eval set exists: tests/memory/fixtures/decision_queries.json (agent-style questions and unanswerable ones, with gold ids), scored by neuralmind decisions eval --queries (QuerySetEval in memory/eval.py), which reports recall@k and MRR as mean and range per query kind and adds every ACTIVE decision’s exact title as a title query. Extend it rather than starting another: add paraphrase queries that share no word with their answer, give QuerySetEval and the CLI a mode, and report keyword, semantic and hybrid side by side per kind. tests/memory/test_query_eval.py holds the Memory Layer wiki’s eval table to the measured numbers, so a new mode’s numbers land in the wiki in the same change.

4.3 Considered and not borrowed

4.4 Using mem0 itself

• Not as a dependency.
  • Its default configuration needs an LLM provider and a vector store, and its telemetry is on by default. Depending on it would undercut both the local-first and the no-telemetry positions.
  • Its Apache 2.0 license would allow adapting its code, but what’s useful is its interface and feature patterns, and this spec already takes those.
• As a neighbour, yes. mem0 remembers people and conversations; NeuralMind remembers the codebase. One agent can run both (docs/comparisons/vs-mem0-zep.md), and PR 5’s examples should include that setup.
• OpenMemory MCP is the closer comparison. mem0 also ships OpenMemory, a local MCP server for Claude Desktop, Cursor and other clients.
  • It runs in Docker as an API, Postgres, Qdrant and a dashboard, and stores memories on the user’s machine.
  • It exposes add_memories, search_memory, list_memories and delete_all_memories.
  • Its documented setup requires an OPENAI_API_KEY.
  • It doesn’t index code.
  • For Claude Desktop and Cursor users it competes more directly than the hosted platform does. The PR that added this section also added it to docs/comparisons/vs-mem0-zep.md.

5. API v1 reference

5.1 Conventions

Base URL.

• Local: http://127.0.0.1:<port>/v1. The port and token come from the discovery file (daemon.py:56-104).
• Server mode: whatever the operator configures.

Auth.

• Authorization: Bearer <token>. Under /v1, the token is not accepted in the query string.
• Unauthenticated routes: GET /v1/health and GET /v1/openapi.json.

Body.

• JSON in UTF-8 only.
• A request body requires Content-Type: application/json; otherwise the response is 415.
• The maximum body is 1 MiB by default (NEURALMIND_API_MAX_BODY_BYTES); larger bodies get 413.
• The size cap also applies to legacy routes.

Response headers.

• Content-Type: application/json; charset=utf-8
• NeuralMind-API-Version: 1
• X-Request-Id: an inbound value matching [A-Za-z0-9-]{1,64} is echoed back; otherwise one is generated.

Host check (defence against DNS rebinding).

• Loopback mode accepts Host values of 127.0.0.1, localhost or [::1], on any port.
• Server mode accepts the configured public_hosts.
• Anything else gets 403 host_not_allowed.

Validation.

• Request and response models are pydantic v2, which is already a base dependency (pyproject.toml:97).
• Models use extra="ignore".
• A failed validation returns 422 validation_error, with details.errors listing {loc, msg, type} for each error.

Pagination.

• Parameters: limit (default 50, maximum 200) and an opaque cursor.
• Response shape: {"items": […], "next_cursor": "…" | null}.

Long-running work.

• Returns 202 Accepted with a Location: /v1/jobs/{job_id} header and {"job": {…}} in the body.
• Passing "wait": true runs the work inline instead.

Formats. Timestamps are ISO-8601 UTC strings; the legacy routes’ epoch floats are converted. Ids are opaque strings.

Success codes.

Error envelope.

{
  "error": {
    "code": "memory_not_found",
    "message": "no memory with id 9b2c…",
    "status": 404,
    "request_id": "a1b2c3",
    "details": {}
  }
}

Error codes.

5.2 Routes

The PR column is the delivery PR (§10). {id} is a project id, {mid} a memory id and {jid} a job id.

5.3 Shapes for the PR 1 routes

All values below are illustrative.

Project

{ "id": "p_3f9a1c2b7d4e", "name": "neuralmind", "path": "/home/me/src/neuralmind", "built": true, "warm": true }

Query

Request: POST /v1/projects/p_3f9a1c2b7d4e/query

{ "question": "how does synapse decay work?", "query_type": "auto", "context_budget": null, "trace": false }

Response 200:

{
  "project_id": "p_3f9a1c2b7d4e",
  "question": "how does synapse decay work?",
  "context": "…",
  "tokens": { "total": 0, "l0": 0, "l1": 0, "l2": 0, "l3": 0 },
  "layers_used": ["L0", "L1", "L3"],
  "reduction_ratio": 0.0,
  "search_hits": 0,
  "trace": null
}

• tokens maps the TokenBudget fields (context_selector.py:33-47): l0_identity → l0, l1_summary → l1, l2_ondemand → l2, l3_search → l3.
• Unlike the legacy route, query_type and context_budget are passed through. Their absence is why the CLI currently falls back to direct mode (cli.py:1048-1087).

Search

Request: {"query": "...", "n": 10}

Response 200:

{ "project_id": "…", "query": "…",
  "results": [ { "id": "…", "label": "…", "file_type": "code", "source_file": "neuralmind/synapses.py", "score": 0.0 } ] }

This is exactly the MCP neuralmind_search shape. The normaliser moves out of mcp_server.tool_search (:153-169) into a shared module that both import.

Memory

A record mirrors DecisionRecord (memory/store.py:79-107):

{
  "id": "9b2c…", "title": "Use SQLite WAL for the synapse store",
  "rationale": "Hooks, the watcher and MCP write concurrently…",
  "commit_sha": "39617aa…", "files_affected": ["neuralmind/synapses.py"],
  "decision_type": "ARCHITECTURE", "confidence": 1.0, "status": "ACTIVE",
  "author": null, "evidence": [], "rejected_alternatives": [],
  "dependency_constraints": [], "tags": ["storage"],
  "created_at": "2026-10-02T12:00:00Z", "updated_at": "2026-10-02T12:00:00Z"
}

Create rules. title and rationale are required; everything else is optional.

• commit_sha defaults to HEAD when the project is a git repository, otherwise "". This matches the CLI. The MCP wrapper defaults to "" (mcp_tools.py:89), which weakens the staleness rules.
• files_affected is normalised to project-relative POSIX paths. Absolute paths inside the project are made relative. Paths outside the project return 422, because find_by_files does exact matches on the stored strings (store.py:576).
• decision_type and status are validated strictly, returning 422. The store silently replaces invalid values with defaults (store.py:338).
• A client-supplied id that already exists returns 409 conflict.
• The handler reads the record back with get(id) after writing. DecisionStore.record() swallows INSERT errors and returns the record anyway, so if the read-back finds nothing the handler returns 500 internal_error (“write did not persist”).
• Duplicate hints (G3). After the write, the handler runs query(title, limit=5, status="ACTIVE", with_scores=True) and drops the new record from the results.
  • If the new record has files_affected, it keeps only matches that share at least one file.
  • It returns up to 3 as possible_duplicates: [{id, title, status, score}].
  • The hint is advisory: nothing is blocked or merged, and the field is present only on the create response.
• Response: 201 with Location: /v1/projects/{id}/memories/{mid}. The body is the record, plus possible_duplicates.

List.

• status=ALL maps to status=None.
• file= may repeat; it uses find_by_files(files, include_invalidated=(status in {INVALIDATED, ALL})).
• Filters (G5). These are applied in the handler and combined with AND:
  • tag= (repeatable; matches any of the given tags)
  • type=
  • author=
  • created_after= / created_before= (ISO dates, inclusive)
  • min_confidence=
• list_all() returns everything, so the handler pages it with limit and cursor after filtering.

Search.

• limit is capped at 25. The store’s normalize_status_filter maps the status: case-insensitive, ALL becomes None, and an unknown value raises ValueError, which the handler returns as 422 validation_error.
• view=compact returns the MCP compact row (mcp_tools.py:176).
• Scores (G4). PR 1 adds one backward-compatible option to the store: DecisionStore.query(…, with_scores=False). When it is True, the method returns (record, score) pairs, where score = -bm25(decisions_fts), so higher is better.
  • The LIKE fallback returns None for the score.
  • v1 returns score on each result. Scores are comparable only within one response.
• Filters. Search accepts the same filters as list.
  • min_confidence maps to the store’s existing min_score parameter. That parameter filters on confidence, not relevance (store.py:668).
  • The other filters are applied after the store returns results. Because the store applies limit in SQL, the handler asks for min(limit × 4, 100) results, filters them, then trims the list to limit.

Patch. Accepts any of rationale, confidence, tags, files_affected, evidence_append[] and rejected_append[]. The handler loads the record, applies the changes, then calls store.update(). Concurrent edits are last-write-wins in PR 1; If-Match on updated_at is optional in PR 2.

Invalidate.

• Returns 404 for an unknown id. The store’s invalidate() is a silent no-op in that case (store.py:487), so the handler checks existence first.
• On success it returns the updated record with status INVALIDATED; the store appends the reason to evidence.

Restore. commit_sha defaults to HEAD. Returns 404 for an unknown id (the store raises KeyError, store.py:509).

Delete. Returns 204, or 404 for an unknown id.

Job

{ "id": "a1b2c3d4e5f6", "kind": "build", "project_id": "p_…", "status": "queued|running|done|error",
  "result": null, "error": null, "created_at": "…", "finished_at": null }

5.4 Locking per route

Taken from a read of the stores; see also perf spec P0-4.

Index routes take registry.lock_for(project). These are build, query, search, wakeup and stats, and in PR 2 also synaptic/structural neighbours, impact, activity and documents.

• They touch mind.embedder, including turbovec’s persistent check_same_thread=False connection (turbovec_backend.py:155).
• They may call _ensure_built().
• This is today’s behaviour (daemon.py:427-482).

Memory routes take no project lock.

• They use a DecisionStore(root) built per request, or one cached per project; its constructor runs idempotent DDL.
• DecisionStore opens a new connection for every call with WAL mode, timeout=30 and autocommit (store.py:281-293), which already makes it safe across threads and processes.

Synapse-only routes (PR 2 feedback, next, synapses/stats) take no project lock.

• They go through mind.synapses, which is guarded by _synapses_lock (core.py:200), and then through SQLite.
• Write endpoints return the number of pairs touched. That makes perf P0-4’s silently swallowed SQLITE_BUSY visible to callers; perf Phase 3 fixes the cause.

6. Security model

6.1 Loopback mode (default; PR 1)

Bind.

• The bind address must be loopback: 127.0.0.0/8, ::1 or localhost.
• PR 1 refuses any other address at startup with a message pointing to server mode. This also closes A3 for the legacy routes.
• PR 2 adds --allow-remote.

Token.

• The existing per-user token from the discovery file (file mode 0600, directory 0700).
• /v1 accepts it in the header only.

Host allowlist. As in §5.1.

CORS.

• The server sends no CORS headers.
• /v1 requires Content-Type: application/json and a bearer header, so a cross-origin browser request is always preflighted, and the preflight fails.
• Together with the Host check, this covers browser-based CSRF and DNS rebinding.

Project registration. Allowed for any directory the daemon user can read, except a reserved-path denylist re-implemented in core (P5), modelled on tier2/self_hosted.py:33-113:

• /, /proc, /sys, /dev, /etc, /boot, /run
• $HOME itself
• ~/.ssh, ~/.gnupg, ~/.aws, ~/.kube, ~/.docker, ~/.config

The path must be a directory and is resolved with realpath first.

Threat model.

• Trusted: processes running as the same OS user. They can read the token file anyway.
• Not trusted: other local users, browsers, and network peers.

6.2 Server mode (PR 2)

Start-up.

neuralmind daemon start --allow-remote --host 0.0.0.0 --port 8765 \
    --config /etc/neuralmind/server.toml [--tls-cert … --tls-key … | --insecure-http]

Projects.

• Defined in config, for example [[projects]] id = "api" path = "/srv/repos/api".
• POST /v1/projects returns 403 registration_disabled.

Tokens.

• Stored in a tokens file as sha256 hashes, each mapped to {actor, role, projects: [...] | "*"}.
• neuralmind daemon token create --actor alice --role builder prints the token once.
• The role comes from the token, never from the request (P3).

Roles.

• reader, builder and admin, with permission names shared with mcp_security.DEFAULT_ROLE_POLICY (mcp_security.py:14-59).
• Each route maps to a permission; for example memories.create maps to neuralmind_record_decision.
• That way one policy governs both MCP and REST.

TLS.

• Either --tls-cert/--tls-key, using stdlib ssl.SSLContext.wrap_socket, or --insecure-http, which acknowledges a TLS-terminating proxy.
• Start-up refuses a non-loopback bind with neither.

Rate limiting.

• mcp_security.RateLimiter per actor, returning 429 with Retry-After.
• The limiter needs a lock first: today it is not thread-safe (mcp_security.py:77-92), and ThreadingHTTPServer is multi-threaded.

Audit. Every mutating call appends AuditTrail.append_event(category="api", action=<permission>, actor=<actor>) (core audit.py:114).

Restricted operations. These are admin-only in server mode:

• validate with write=true
• memory DELETE
• admin/shutdown

Config bridge.

• tier2’s self_hosted.bind_address and port (tier2/config.py:64-80) feed server mode through an adapter that lives in tier2.
• These would be the first consumers those fields have ever had.

6.3 What does not change

NeuralMind itself still transmits no repository content. A team that runs server mode is moving its own data to its own server, and the docs must say exactly that, using the safe phrasing that tests/test_docs_claims.py recommends.

7. Clients

7.1 Python client: neuralmind/client.py (PR 1)

The client is stdlib-only (urllib), finds the daemon the same way daemon_client.connect() does, and adds no import-time cost.

from neuralmind.client import NeuralMindClient

nm = NeuralMindClient()  # local daemon, found via the discovery file
# nm = NeuralMindClient("https://nm.internal:8765", token=os.environ["NEURALMIND_API_TOKEN"])

repo = nm.project(".")   # POST /v1/projects (idempotent); returns a handle
repo.build(wait=True)

ctx = repo.query("how does synapse decay work?")
print(ctx.context, ctx.tokens.total)

repo.memories.add(
    title="Use SQLite WAL for the synapse store",
    rationale="Hooks, the watcher and MCP write concurrently; WAL lets readers proceed.",
    files=["neuralmind/synapses.py"],
)
for m in repo.memories.search("sqlite concurrency"):
    print(m.id, m.title, m.status)

Return types. Small frozen dataclasses (QueryResult, SearchHit, Memory, Job, Project). Each also exposes .raw, the full response dict, so a field added later is reachable before the client is updated.

Errors. NeuralMindAPIError(status, code, message, details, request_id), with subclasses NotFound, Unauthorized, Forbidden, ValidationFailed, Conflict, RateLimited.

Connection settings.

• NEURALMIND_API_URL and NEURALMIND_API_TOKEN override discovery.
• autostart=False is the default. Perf WP 2.4 owns the auto-spawn policy; the client exposes the switch but does not decide it.

Timeouts. 30 s by default. query uses 120 s, and build(wait=True) 600 s, matching daemon_client.py.

7.2 Other clients

CLI (PR 2).

• daemon_client moves to /v1.
• neuralmind search is routed through the daemon too; today it is always direct (cli.py:1852-1862).
• Legacy routes then return Deprecation: true and Link: </v1/…>; rel="successor-version".
• Legacy routes are removed no sooner than two minor releases after that.

Dashboard (PR 3). It reads /v1 and /v1/events. server.py’s /api/* routes become thin adapters, then are deleted.

MCP over HTTP (PR 4).

• /mcp uses the mcp SDK’s Streamable HTTP session manager, and its tool handlers call the daemon’s dispatch() with the shared ProjectRegistry. This is also what perf WP 2.4 needs.
• Auth is a token from the same tokens file; OAuth 2.1 comes later.
• The SDK needs ASGI (starlette, uvicorn), which arrives transitively through mcp (pyproject.toml:88). See open decision 4.

TypeScript client (PR 5, optional). Generated from the committed OpenAPI snapshot.

8. Packaging and Docker (PR 3)

Dockerfile changes.

• EXPOSE 8765.
• VOLUME ["/data", "/repos"].
• A HEALTHCHECK that calls python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/v1/health')", because the slim image has no curl.

docker-compose.yml changes.

• Add a real command: running neuralmind daemon start --foreground --allow-remote --host 0.0.0.0 --port 8765 --config /config/server.toml --insecure-http.
• Publish the port on loopback by default (127.0.0.1:8765:8765); operators put a proxy in front.
• Set NEURALMIND_LICENSE_PATH=/app/license.json.
• Mount repositories at /repos.

Repository mounts must be writable for now. .neuralmind/ lives inside each project (state_dir.py). PR 3 investigates letting state live under NEURALMIND_DATA_DIR so repositories can be mounted read-only.

README. A “Run the NeuralMind API with Docker” block: docker compose up, then curl localhost:8765/v1/health.

The end-state port map:

9. Coordination with the performance programme

Ordering.

• PR 1 doesn’t depend on perf Phase 1 or 2. It touches daemon routing and new modules, not hooks or core.py. Its only store change is the backward-compatible with_scores option on DecisionStore.query (§5.3).
• PR M changes the decision schema (§4.2). It touches only memory.db, not synapses.db, so it doesn’t collide with perf Phase 3’s synapse migration.
• If perf Phase 2 merges first, PR 1 rebases onto its daemon changes. The route table makes that merge mechanical.

10. Delivery plan

Every PR ships with the CLAUDE.md docs and SEO checklist in the same PR.

11. Open decisions

1. Seats in server mode. Commercial terms say features aren’t gated and seats beyond one are a Team license. Recommendation: core doesn’t enforce seats; tier2 registers a hook that warns when the number of distinct token actors exceeds licensed seats.
2. Project id format. A hash (recommended: stable, no state, nothing to leak) or a slug. Server mode gets aliases either way.
3. SSE auth (PR 3). EventSource can’t set headers. Recommendation: the dashboard uses fetch streaming with the bearer header, and /v1 stays header-only.
4. ASGI dependency. If PR 4 relies on starlette and uvicorn, declare them explicitly rather than inheriting them through mcp. Recommendation: /v1 stays on the stdlib server in every mode, and ASGI is used only for /mcp, in the same process and sharing the registry.
5. Path redaction. Should path be hidden from the reader role in server mode? Recommendation: yes.
6. Public name. Recommendation: “NeuralMind API (self-hosted)” in public docs, so nothing implies a hosted service; “local API” in engineering docs.
7. Hard delete. Keep it (mem0 parity, and a way to erase a mistaken record), but admin-only in server mode. Invalidate stays the recommended path.
8. A “propose decisions” endpoint (§4.3). It would be the one mem0-style use of a model. Recommendation: not now. Revisit after PR M, once there is evidence of how people use decision memory. If it is built: local model only, opt-in, and it stores nothing.
9. Default search mode after PR M. Recommendation: make hybrid the default only if the eval shows it still ranks exact-title matches first (the eval’s title kind; keyword ranks 30 of 30 first). Otherwise keep keyword as the default and make hybrid opt-in.

12. Side findings (separate fixes, not in PR 1)

Found while surveying for this spec; each was verified against 39617aa.

1. Fixed. neuralmind_memory_search with status: "all" matches nothing. The schema advertises “all” (memory/mcp_tools.py:480), but tool_memory_search passes the string straight to DecisionStore.query, which treats only None as “all statuses” (:193-226). Fix: DecisionStore.query and list_all normalise the filter (case-insensitive, ALL → None, unknown → ValueError), so MCP and the CLI agree; neuralmind decisions query --status takes INVALIDATED and any case.
2. Fixed. InvalidationEngine raises AttributeError in its error path. The event-bus failure branch logs event.id (memory/invalidate.py:387), but InvalidationEvent has decision_id, not id (:195-212). A failed publish raised mid-scan, after the store write. Fix: logs event.decision_id; tested with a failing bus.
3. Fixed. “Not built” is reported as a security denial. GraphNotBuiltError subclasses RuntimeError (core.py:129), and MCP maps every RuntimeError to code: "security_denied" (mcp_server.py:1335-1336). So did every other tool RuntimeError and any OS PermissionError. Fix: MCP returns index_not_built with a hint, and security_denied only for the security manager’s own AccessDeniedError and RateLimitExceededError, with a reason of rbac or rate_limit. Other failures return the plain error.
4. The compose service restart-loops, and the license path is wrong (A7).
5. Fixed. neuralmind/memory/cli.py is dead code. It defines a second decision store at .neuralmind/memory/decisions.sqlite with a different schema and lowercase statuses, and its build_memory_subparsers is never called. The live path is neuralmind decisions → DecisionStore. Fix: deleted. Nothing imported it, and its memory group would have collided with the live neuralmind memory commands, so it could not have been wired in as written. No code reads decisions.sqlite; a leftover copy can be deleted.
6. docs/use-cases/always-on.md disagrees with the shipped service templates. It says serve runs on 8787; the systemd and launchd templates use 8765.
7. Fixed. The Memory Layer wiki overstates what search covers. docs/wiki/Memory-Layer.md:8 says search covers “titles, rationales, and evidence”. The FTS table indexes only title and rationale (store.py:147-153), and so does the LIKE fallback (store.py:778). The MCP tools also called keyword search “natural language”, yet every word must match, so a sentence-length query finds nothing. Fix: the wiki and the tool descriptions name exactly the indexed fields, and tests/memory/test_search_scope_docs.py holds them to the FTS columns. PR M still adds evidence and tags to search (§4.2). Follow-up, also fixed: search now matches any word of the query, so a sentence finds what its keywords find, and the docs say so (§4.2, “The keyword half has landed”).

13. Sources

• mem0 OSS REST API: https://docs.mem0.ai/open-source/features/rest-api
• mem0 platform pricing (third-party summaries, September–October 2026): https://toolradar.com/tools/mem0-ai/pricing, https://costbench.com/software/ai-memory-context/mem0/free-plan/, https://usagepricing.com/blueprint/mem0
• NeuralMind’s existing mem0 comparison: docs/comparisons/vs-mem0-zep.md
• mem0 memory expiration: https://docs.mem0.ai/platform/features/memory-expiration
• mem0 memory filters (get memories): https://docs.mem0.ai/api-reference/memory/get-memories.md
• mem0 API reference (history, batch, export, webhooks, feedback): https://docs.mem0.ai/api-reference
• OpenMemory MCP: https://mem0.ai/openmemory-mcp and https://docs.mem0.ai/openmemory/quickstart
• mem0 telemetry default (summaries of the source): https://deepwiki.com/mem0ai/mem0/11.2-telemetry-and-analytics, https://instagit.com/mem0ai/mem0/how-does-mem0-handle-telemetry-and-data-collection-and-can-it-be-disabled