Memex AI Documentation

Overview

Memex AI is the living specification and verification layer for AI-native software teams. It provides a shared graph that both humans and AI coding agents read from and write to, ensuring every participant, human or machine, acts on the same understanding of what's being built and why.

The platform captures interconnected primitives: Specs (the objectives and their living narrative), decisions (the choices that shape implementation), tasks (a dependency-aware execution graph), acceptance criteria (observable conditions verified from CI), and standards (clause-grain, prescriptive rules that can't silently rot). Together they form a single source of truth that replaces scattered Slack decisions, stale wikis, and disconnected ticket trackers.

Quick Start

1. Connect your first agent Point any MCP-compatible AI coding agent (Claude Code, Cursor, Windsurf, Cline, or a custom agent) at your Memex AI server. The agent immediately gains access to your entire decision graph through standard MCP tool calls.
2. Create your first Spec Define an objective: the full context that makes every downstream choice intelligible. Surface the blocking decisions, scope tasks with explicit dependencies and acceptance criteria, and link the standards that apply. It takes less time than setting up a Jira epic, and it's immediately useful for both humans and agents.
3. Watch the cycle work Agents load scoped context, check decisions and dependencies, and produce execution plans. You review and approve. They implement, tagging tests to acceptance criteria. The board advances through draft, specify, build, verify, and done as the work lands.

MCP Configuration

Memex AI uses Streamable HTTP MCP transport. Point any MCP-compatible AI tool at your Memex AI server's /mcp endpoint with your API key. Below are configuration examples for popular tools.

Claude Code

Cursor

Windsurf

Cline

Specs

A Spec is the canonical unit of work in Memex AI. It articulates what the team is trying to achieve and why. Not a one-line epic title, but the full context that makes every downstream choice intelligible. Every unit of work is a Spec; "Spec" is the noun.

Specs are documents, not records. Their content lives in ordered sections: overview, design, architecture, risks, and custom sections. Each section is independently addressable: agents edit one section at a time (sending only a few hundred tokens per edit), and humans can comment on individual sections during review.

Phases: a Spec moves forward through five phases, with orthogonal paused / archived flags.

• DRAFTInitial state. The objective and narrative are being shaped.
• SPECIFYDecisions are surfaced and resolved; scope acceptance criteria are written. No tasks yet.
• BUILDDecisions are resolved, so work crystallises into tasks. Agents execute against the Spec.
• VERIFYEvery acceptance criterion is checked against CI before the Spec is called done.
• DONEVerified and closed. Still queryable for historical context.

Before any forward move, an agent runs assess_spec to walk a deterministic readiness rubric. Tasks exist only in the build phase: a task in draft or specify is a guess pretending to be a commitment, so decisions get resolved first.

Tags: Specs support scoped and flat tags for categorisation (priority::high, bug). A scoped tag is mutually exclusive within its scope.

Section-level commenting: Reviewers can add comments to individual sections, including question-typed comments that surface a knowledge gap. The Spec detail URL is shareable. Paste it into Slack and see the title, phase, and unresolved comment count.

Decisions

Decisions are first-class objects in Memex AI, not afterthoughts buried in Slack threads or locked in AI conversation history. Every non-obvious choice gets a handle, status, options considered, and rationale.

Handles: Decisions are numbered per Spec: dec-1, dec-2, dec-3, etc. This keeps references human-readable in conversation ("see dec-3 on the auth Spec") while UUIDs handle cross-Spec references internally.

Options and trade-offs: Each decision records the options considered, with labels, descriptions, and trade-offs for each. This gives agents and future humans the full context of what was weighed.

Statuses:

• CANDIDATEAn agent-proposed decision awaiting human review. Approve it to open, or reject it with a reason. Candidates are how agent-made choices surface for sign-off rather than landing silently.
• OPENA decision that needs to be made. Open decisions block dependent work, preventing agents from building against unresolved ambiguity.
• RESOLVEDA decision that has been made. Resolution records the chosen option, the rationale, and which options were rejected. Resolved decisions constrain downstream implementation and inform standards. Each resolved decision carries at least one implementation acceptance criterion that proves the choice was honoured.

Re-opening decisions: When priorities shift or new information surfaces, you can re-open a resolved decision via update_decision (status=open). The system traces the impact downstream, marking affected work as potentially stale and flagging related standards for review.

Tasks

Tasks in Memex AI are not a flat backlog. They form a directed acyclic graph (DAG). Each task has a goal, acceptance criteria, and explicit dependencies on both other tasks and decisions. Tasks exist only once a Spec is in the build phase.

Handles: Like decisions, tasks are numbered per Spec: t-1, t-2, t-3, etc. Human-readable in conversation, UUIDs internally for cross-Spec dependencies.

The dependency graph means the system always knows what's ready to start, what's blocked, and why. Agents call list_tasks with readyOnly and the system returns only those that are not-started with no open blockers (all dependencies met and all blocking decisions resolved).

Status lifecycle:

• NOT STARTEDCreated, waiting for dependencies or pickup
• BLOCKEDDependencies not met or blocking decisions unresolved
• IN PROGRESSActively being worked on
• COMPLETEFinished, which may unblock downstream tasks

Acceptance criteria: Each task can be linked to acceptance criteria: observable conditions that must hold for the work to count as done. They are verified from CI, not self-reported.

Escalation bridges: When an agent hits something it cannot do, it pushes the task back up to a human Issue with kick_task_to_issue. In the other direction, an open Issue (a bug or todo) is pulled down into agent work with convert_issue_to_task, which mints a verifying acceptance criterion and auto-resolves the Issue when the task completes and the test goes green.

Acceptance Criteria

Acceptance criteria (ACs) are observable, testable conditions written into the Spec. They are the difference between "the agent says it's done" and "done is a fact you can see."

There are two flavours. Scope ACs are manager-authored, plain-English outcome commitments that define what success looks like for the Spec. Implementation ACs are technical assertions spawned from a resolved decision: each resolved decision carries at least one, proving the choice was honoured.

Verification from CI: agents link a test to an AC with a single comment line, no new tooling. As tests run in CI, each AC derives a live state:

• VERIFIEDAll tagged tests pass
• FAILINGA latest emission for the AC is a failure
• STALEAll pass, but the oldest is more than seven days old
• UNTESTEDNo tagged tests yet

The verify phase shows exactly which ACs are still untested before you call a Spec done. Months later, if a change anywhere breaks an AC from this Spec, CI catches it and the AC flips to failing. Nobody has to remember to re-check.

Standards

Standards are prescriptive, clause-grain rules for how software gets built. Not "here's how auth works" but "when you modify auth, do X, never do Y, verify with Z." They represent institutional knowledge in a form that agents reliably consume and act on, and they are the managed, multi-agent evolution of CLAUDE.md, cursor rules, ADRs, and wikis.

Authored as clauses, not prose. A standard is a set of sections, each a list of self-contained clauses with addressable cl-N handles. Agents and humans edit at the clause grain (add_clause / edit_clause / delete_clause), so a single rule can change without rewriting the document.

Cross-Spec and scoped. Standards are not owned by any one Spec. An agent loads only the clauses relevant to the task it claims, injected into its context automatically. Every clause traces back to the decisions that produced it.

Drift and the Drift Inbox: when an agent sees the code and a rule diverge during execution planning, it flags drift with flag_drift. If the rule itself is wrong, it proposes a corrected version with propose_standard_change. Either lands as a typed comment in your Drift Inbox with a diffed proposal, for the standard owner to accept or reject. You stay in control of the codebase; nothing changes silently.

Drift Detection

Drift detection is the feature that makes Memex AI fundamentally different from a wiki. Instead of relying on humans to remember to update documentation, the system actively monitors for divergence between standards and reality through four mechanisms:

• Agent-reported drift: During execution planning, agents compare what they find in the codebase against what the standard prescribes. If there's a mismatch, the agent flags it with evidence: "code says X, standard says Y."
• Decision-triggered drift: When a decision is resolved or re-opened, the system automatically identifies which standards are affected and marks them for review. A new auth decision, for example, flags the auth standard.
• Implementation-triggered drift: When a task is completed, the system prompts a review of any standards that cover the modified domain. The implementation may have introduced patterns or constraints not yet reflected in the standard.
• The Drift Inbox: Flagged mismatches queue with a diffed proposal to fix the code or change the rule. The standard owner accepts or rejects each one. Nothing changes silently.

Decision Capture

Nobody will log decisions manually. That's a well-known failure mode of every knowledge management system. Memex AI captures decisions as candidates instead, with a human always in the loop.

How it works:

• Surfaced from the spec: Before build, the implicit decisions hiding in a spec or doc you bring are surfaced as blocking questions and routed to the right person.
• Proposed during build: Every blocking choice an agent makes mid-build lands as a candidate decision for you to approve or reject, in the UI or from your coding agent. No agent quietly decides your architecture.
• Review flow: Candidates carry the options, rationale, and context. Approve to open, or reject with a reason that is preserved. Like a merge request, but for decisions.
• Into the graph: Approved decisions become first-class objects with provenance. They block tasks, constrain implementations, and trigger standard reviews.

Human-Machine Collaboration

Memex AI is designed for the team you actually have: humans and AI coding agents working in parallel, often without direct visibility into each other's work. The collaboration model is explicit about what each side brings:

What humans bring:

• Goals and intent: the why behind the work
• Decisions with rationale that others can trace
• Priority judgement when trade-offs have no clear answer
• Review of agent-extracted decisions and execution plans
• Domain knowledge that doesn't exist in the codebase

What machines bring:

• Tireless execution against well-defined tasks
• Automatic extraction of decisions from conversations
• Drift detection: flagging when docs diverge from code
• Dependency checking before every implementation
• Parallel work across the entire codebase, simultaneously

The shared graph is the bridge: one source of truth that both humans and machines read and write to. Not a human tool with an API bolted on. Not an AI tool with a dashboard bolted on.

Tech Stack

MCP Transport

Memex AI uses Streamable HTTP transport over the /mcp endpoint. Each tool call is a POST request with a JSON-RPC payload. The server responds synchronously. No streaming needed for the current implementation.

All read tools return formatted text optimised for LLM consumption: structured markdown with clear delimiters, stable IDs, and status indicators. Not raw JSON. The text format is designed to be scannable by both humans (reading in a terminal) and agents (parsing for IDs and status). All write tools accept structured parameters (JSON schema) and return confirmation with any cascading effects described.

There is no vendor lock-in, no proprietary plugins, and no custom integrations needed. If your AI tool supports MCP (and most modern ones do), it works with Memex AI.

MCP Tools Reference

The 52 tools below are the complete coding-agent surface any connected agent reaches via MCP. This reference is generated from the canonical @memex/shared tool manifest, so it cannot drift from the live server: adding, removing, or renaming a tool forces a matching change here. Tools are grouped by the phase they belong to; read tools work in any phase.

On-demand guidance

• get_information(topic?) Fetch on-demand operating guidance. Call with no args for the topic index; call with topic='<slug>' for depth. Most operating guidance lives here (session-init prompt is intentionally tiny).

Read (any phase)

• list_memexes() List the Memexes you have access to, grouped by namespace; call first when working across more than one.
• list_docs(memex?, docType?, tags?) List active Specs in a Memex with decision/task counts and lineage; filter by docType (defaults to spec) and/or tags.
• get_doc(ref) Get a document with all sections, decisions, tasks, comments, blockers, plus its public URL.
• export_doc(ref) Export a spec as lossless markdown with every comment thread expanded inline at its anchor (for paste into an external LLM/editor).
• list_tasks(ref, readyOnly?) List tasks on a document; readyOnly returns only unblocked, not-started tasks (replaces get_ready_tasks).
• list_comments(ref, types?, mode?) List comments by target, by document, or by type; mode=review/task_notes shape the output.
• search_memex(memex?, query, kind?, includeArchived?, includeCurrentDoc?, limit?) Semantic + full-text search across Specs, Standards, docs, and Decisions in the active Memex.
• search_issues(memex?, query, includeArchived?, limit?) Search Issues across the Memex (scoped to kind:issue) — cross-spec discovery of a bug/todo registered on any Spec.
• get_spec_roles(ref) List a Spec's editors (reviewers are implicit and not enumerated) and report the caller's own resolved role. Read-only.

Specify phase — documents & decisions

• create_doc(memex?, title, purpose?, docType?, decisions?, promoteFromTaskRef?, promoteFromIssueRef?) Create a new Spec (or other docType); optional decisions seed, promoteFromTaskRef / promoteFromIssueRef preserves lineage.
• update_doc(ref, status?, title?, tags?, removeTags?) Update a document's status, title, and/or tags; transitions a Spec through draft→specify→build→verify→done.
• add_section(ref, sectionType, content?, clauses?, title?, description?) Add a new section to a document; the (doc, sectionType) pair is unique. STANDARDS are authored as clauses: pass clauses[] (one aspect each), not content; other doc types pass content. The wrong field for the doc type is rejected with guidance.
• update_section(ref, content, sectionType?, description?) Update the markdown content of a NON-standard document section (+ optional sectionType key / description). Blocked on standards — edit those at the clause grain via add_clause/edit_clause/delete_clause. A sectionType collision fails with a readable error.
• add_clause(ref, body, position?) Append (or insert at a position) a clause to a STANDARD section — one self-contained aspect. Standards only; the new clause gets an addressable cl-N handle.
• edit_clause(ref, body) Edit a STANDARD clause's body by its cl-N ref; the section content (the join of its clauses) regenerates. Standards only.
• delete_clause(ref) Soft-delete a STANDARD clause by its cl-N ref; the cl-N is frozen (never reused) and siblings are not resequenced. Standards only.
• retitle_section(ref, title, sectionType?) Change a section's heading (and optionally its machine key); content is untouched. A sectionType collision fails with a readable error.
• delete_section(ref) Soft-delete a section (→ status=deleted); hidden from get_doc / lists / search but restorable. Remaining sections resequence to stay contiguous.
• create_decision(ref, title, context?, status?, options?) Create a decision on a document; status='candidate' records an agent-extracted candidate awaiting review.
• update_decision(ref, status?, title?, context?, resolution?, chosenOptionIndex?) Two modes: edit-in-place (title/context/resolution/chosenOptionIndex on any status) OR reopen (status='open' on a resolved decision). One per call. resolve_decision is the named verb for new resolutions.
• delete_decision(ref) Soft-delete a decision (→ status=deleted); hidden from get_doc / default list_decisions / UI tabs but queryable via ?include=deleted. No hard delete — update_decision restores it. Use when a decision was created in error (b-97).
• resolve_decision(ref, resolution, chosenOptionIndex?) Resolve a decision with an explanation; may unblock waiting tasks. chosenOptionIndex marks a structured option.
• approve_candidate(ref) Approve a candidate decision, transitioning it from status=candidate to status=open.
• reject_candidate(ref, reason) Reject a candidate decision (→ status=rejected); the reason is preserved as the resolution.
• assess_spec(ref, mode, target?, codeGrounding?) Run a deterministic Spec assessment: phase rubric, narrative freshness, comments survey, or consolidate.
• publish_spec(ref, status?) Transition a Spec out of draft (defaults to 'specify'); refuses already-published Specs.

Build phase — tasks

• create_task(ref, title, description, acceptanceCriteria?, sectionRef?) Create a task (build-phase only); resolve open decisions first. Include acceptance criteria.
• update_task(ref, status?, title?, description?, acceptanceCriteria?, sectionRef?, addBlockerRef?, removeBlockerRef?) Update a task: status, title, description, acceptanceCriteria, sectionRef, add/removeBlockerRef.
• delete_task(ref) Delete a task; also removes its blockers and dependencies.

Build phase — standards protocol

• flag_drift(standardSectionId, observation) Flag drift on a standard section — post a typed `drift` comment (sourced 'agent') describing the gap between the rule and observed reality. Use when the rule is right but the codebase has drifted; if the rule itself is wrong, use propose_standard_change instead.
• propose_standard_change(standardSectionId, proposedContent, rationale?) Propose a corrected version of a standard section. Lands as a typed `plan_revision` comment (sourced 'agent') with the full proposed replacement and a rationale, for the standard owner to accept or reject in the Drift Inbox.

Build phase — issues & escalation

• register_issue(memex?, spec_ref?, title, body, type, severity?, promote_to_spec?) Register a bug/todo Issue against a Spec (any phase). With NO spec_ref, persists nothing and returns a two-option assist (promote-to-Spec or a ranked list of active Specs) — no silent default home (std-5).
• list_issues(ref, type?, status?) List Issues on a Spec, optionally filtered by type (bug|todo) or status.
• get_issue(ref) Get a single Issue by canonical ref (returns type, status, severity, title, body).
• update_issue(ref, title?, body?, severity?) Update an Issue's title/body/severity. Status transitions go through resolve_issue.
• resolve_issue(ref, resolution) Close out an Issue by setting its status to 'resolved' or 'wont_fix'.
• convert_issue_to_task(ref) Down-bridge: atomically pull an open Issue into an agent Task, mint a verifying implementation AC + task_satisfies_ac link, and set the Issue → converted. Auto-resolves when the Task completes and the AC goes green.
• kick_task_to_issue(ref, reason) Up-bridge (4th escalation): push an agent-impossible Task back into a human todo Issue and delete the Task. If the Task came from an issue→task conversion, reverts the origin Issue to open instead of duplicating.

Roles & assignment

• set_spec_role(ref, user, role?) Set a user's role on a Spec: editor (promote) or reviewer (demote). Independent of assignment; no last-editor lock (a Spec may hold zero editors). Defaults to editor. Identify the user by email or id.
• assign_spec(ref, user?) Assign a user to a Spec (ticket-style responsibility). Idempotent; independent of role (a reviewer can be assigned). Omit user to self-assign. Identify the user by email or id.
• unassign_spec(ref, user) Remove a user's assignment from a Spec. Idempotent; leaves the user's role untouched. Identify the user by email or id.

Acceptance criteria

• create_ac(ref, kind, statement, status?, parent_decision_ref?) Create an Acceptance Criterion under a Spec. kind='scope' (manager-authored, plain-English; parent=spec) or 'implementation' (agent-spawned from a resolved Decision; technical; pass parent_decision_ref).
• list_acs(ref, kind?, status?) List ACs on a Spec, optionally filtered by kind or status.
• get_ac(ref) Get a single AC by canonical ref (returns kind, status, statement).
• update_ac(ref, statement) Update an AC statement by ref. Only statement is mutable here; kind is fixed at creation; status transitions via accept_ac / reject_ac.
• delete_ac(ref) Hard-delete an AC by ref. FKs cascade parent links and task_satisfies_ac. Prefer reject_ac for considered-and-dismissed ACs.
• link_ac_to_decision(ac_ref, decision_ref) Attach a parent-Decision link to an existing AC (for cross-cutting Implementation ACs spawned from multiple Decisions). Typical Decision-spawned ACs use create_ac's parent_decision_ref instead.

Comments & human handoff

• add_comment(ref, authorName, content, type?, referenceRef?, anchorOffset?) Add a comment to a section, decision, or task; type=question surfaces a knowledge gap to the user. anchorOffset anchors a geo-comment to a point in a section.
• update_comment(ref, status, resolution?) Update a comment; today status='resolved' resolves it with an optional resolution note.
• memex__send_slack_message(memex?, channelOrUser, text, specRef?) Send a Slack message as the current user via their connected Slack account — for AI→human handoffs.
• memex__send_discord_message(memex?, text, specRef?) Send a message to the org's configured Discord webhook channel — for AI→human handoffs.

Auth Model

Memex AI has two authentication paths: one for agents, one for humans. Both resolve to the same multi-tenant account model.

Agents (MCP connections)

API keys use the mk_ prefix for identification. The server hashes the key, resolves it to its tenant, and scopes every query and mutation to that tenant at the middleware and unified mutation layer. The key's label (e.g., "claude-code", "cursor", "ci-agent") is recorded for audit.

Keys can be revoked without affecting other keys on the same tenant.

Humans (React UI)

Authentication is native: hand-rolled JWTs, scrypt password hashing, and email magic links delivered via Postmark. No Firebase, no third-party identity provider. The server verifies the JWT, resolves the user and their tenant, and proceeds. Org membership grants access to every Memex in that org.

Permissions & governance

Permissions are enforced on the server, not suggested to the agent. An agent connected with an API key can only ever act inside its own tenant, and every read and write is scoped at the middleware and mutation layer. Asking for a resource you cannot access returns 404, never 403: the system never reveals that a resource it won't show you exists.

Per-Spec roles. A user is an editor or a reviewer on a given Spec (set_spec_role). Roles are independent of assignment: a reviewer can still be assigned a Spec (assign_spec) for ticket-style responsibility. There is no last-editor lock, so a Spec may hold zero editors.

What agents can and cannot do. Agents do the operational work: resolving decisions, creating and updating tasks in build, tagging acceptance criteria, flagging drift, and proposing standard changes for human approval. They cannot manage the tenant itself: users, API keys, and org membership stay with humans. Phase transitions to done are a human call, never the agent's.

Requirements

Memex AI can be self-hosted on your own infrastructure for complete data sovereignty. It runs as a single container serving both the REST API and MCP endpoint. The requirements are minimal:

• Node.js: v22 or later (TypeScript runtime)
• PostgreSQL: v16 or later with the pgvector extension (the decision graph, task DAG, acceptance criteria, standards, and semantic search)
• SMTP / Postmark: for human authentication email (magic links). Auth is native, so no Firebase or external identity provider is required. Agents authenticate via API keys.
• Anthropic API key: for the AI agent (decision surfacing, drift detection). Bring your own key; nothing is sent to Mindset.

Configuration

Configure your self-hosted instance through environment variables:

Deployment

Memex AI runs as a single container serving both the REST API (/api/*) and MCP endpoint (/mcp). Basic deployment steps:

The server (API + MCP) listens on 8080 and the React UI on 5173. Point your agent's MCP configuration at https://your-server:8080/mcp; the UI connects to the same server on /api/*. API keys (with the mk_ prefix) are generated from the UI.