Memex Documentation
Getting Started
Understanding Memex
A short getting-started guide to how Memex works, end to end. Read it yourself, or hand the markdown to your coding agent.
Overview
Memex 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 six interconnected primitives:
Together they form a single source of truth that replaces scattered Slack decisions, stale wikis, and disconnected ticket trackers.
Quick Start
-
Connect your coding agent
Run the Memex installer in your terminal. It connects the Memex MCP server to Claude Code and Claude Desktop with one browser sign-in. For any other MCP-compatible agent (Cursor, Windsurf, Cline, or a custom agent), pick your tool in Connect your coding agent below. The agent then reaches your entire decision graph through standard MCP tool calls.
Run in your terminal
npx -y memex-ai installJust ask your agent (after installation)
i want to use the memex mcp -
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.
Just ask your agent
create a spec in memex for... -
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.
Just ask your agent
is spec (URL) ready to build?
Example prompts
Once Memex is connected, ask in plain language. Three things people do most often:
-
Get up to speed on a Spec
Memex finds the Spec and reads back its decisions (resolved and open), its tasks and their status, and any open issues, so you can pick up work without rereading the whole thread.
Try asking
Summarise the checkout redesign Spec in Memex: what's been decided, what's still open, and which tasks are in progress. -
Shape a new Spec
Memex creates a draft Spec with an overview, and records the choices the work depends on as open decisions with their options and trade-offs, ready for the team to settle.
Try asking
Start a Spec in Memex for adding a dark mode, and record the open decisions we'd need to make. -
Record a decision and plan the work
Memex resolves the decision with your reasoning on the record, then adds a task for the work it implies. Anyone who opens the Spec later sees what was chosen and why.
Try asking
On the checkout Spec, resolve the open decision about payment retries: we'll retry twice, then email the customer. Then add a task to build it.
MCP Configuration
Memex uses Streamable HTTP MCP transport, point any MCP-compatible AI tool at the /mcp endpoint and authenticate with an MCP token (Claude uses one-click OAuth instead). Pick your tool in Connect your coding agent below for the exact config.
Connect your coding agent
Memex speaks Streamable HTTP MCP at /mcp. Pick your tool below for the exact config. Every tool points at the same server URL and authenticates with a Bearer MCP token (the mxt_ prefix), except Claude, which supports one-click OAuth with no token.
Claude supports one-click OAuth, no token needed. In Claude.ai or Claude Desktop, open Settings → Connectors → Add custom connector and paste the URL:
For Claude Code, add it from the terminal:
The first MCP-touching prompt opens the Memex consent screen in your browser; sign in and approve. A free Memex account is all you need. One connection covers every Memex you are a member of, personal and organization, and follows your membership as it changes. To disconnect, remove the connector under Settings → Connectors, or in Claude Code run claude mcp remove memex.
mxt_ prefix. The Memex installer creates one per device; see and revoke them in Memex under Settings → Integrations → MCP Tokens. For self-hosted deployments, replace memex.ai with your instance's host (e.g. https://memex.your-domain.com/mcp).Troubleshooting
Common connection issues & fixes
| Symptom | Fix |
|---|---|
Client shows 0 tools after connecting | Fully quit and relaunch your client, the first connection often needs a clean restart to pick up the auth state. In Claude Code, run a prompt that touches MCP to trigger the flow. |
| Tools return "You are not a member of …" | One connection covers every Memex you are a member of, personal and organization, and follows your membership as it changes. Check in the web app that you belong to the Org that owns the Memex; once you are added, the same connection reaches it with no reconnect. |
401 / invalid_token on a tool call | Your access token expired, the grant was revoked, or the MCP token is wrong. Reconnect to refresh the OAuth grant (Claude), or check the mxt_ MCP token in your config (every other tool). Tokens are listed, and can be revoked, under Settings → Integrations → MCP Tokens. |
| Browser OAuth can't complete (CI, headless, no display) | Use an MCP token (the mxt_ prefix) as a Bearer header instead. It is the default for every tool except Claude, and needs no browser at call time. |
list_memexes returns nothing | Your account isn't a member of any Memex yet under this connection. Sign in to the web app, confirm your Org / Memex membership, then reconnect. |
| A write tool is refused on a public Memex | Public Memexes are read-only for non-members, read tools work, writes need membership. Join the Org, or use a Memex you belong to. |
Still stuck? Email us at support@memex.ai, we're happy to help.
Core Concepts
Specs
A Spec is the canonical unit of work in Memex. 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, 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 decision (verb update, status=open). The system traces the impact downstream, marking affected work as potentially stale and flagging related standards for review.
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.
Tasks and Issues
Tasks and Issues are created by the coding agent during a coding session, as a record humans can refer to. As the agent works, it writes down the units of work it's executing (tasks) and the problems it runs into but can't resolve in-session (issues), instead of those surfacing only in the transcript and getting lost when the session ends.
Tasks in Memex 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 (of: '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.
Issues, so nothing gets lost in a coding session: When the agent hits something it can't resolve, it records an Issue with kick_task_to_issue rather than burying it in the transcript. Issues are surfaced in the Memex UI, where a human can see them at a glance and resolve them, instead of them being lost in the coding session. In the other direction, an open Issue (a bug or todo) is pulled back down into agent work with issue (verb convert-to-task), which mints a verifying acceptance criterion and auto-resolves the Issue when the task completes and the test goes green.
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 (the clause tool's add / edit / delete verbs), 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 standard (verb flag-drift). If the rule itself is wrong, it proposes a corrected version with the propose-change verb. 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.
Working with Memex day to day
Day to day, the work moves a Spec through the phases, and each phase has a clear set of outputs. Knowing what "done" looks like for each phase is the heart of working with Memex.
Start a spec from a Jira or Linear ticket
Most work starts as a ticket in your tracker. Memex has no built-in tracker connection. Your coding agent brings the ticket in, using your tracker's own MCP server alongside the Memex MCP server.
- Connect your tracker's MCP server to your coding agent, following your tracker's own instructions (Atlassian for Jira, Linear for Linear).
- Connect the Memex MCP server as described in Connect your coding agent.
- Ask your agent to create a spec from the ticket, for example:
create a Memex spec from ticket PAY-482. The agent reads the ticket through the tracker's MCP server and creates a draft Spec in Memex with it.
From there the Spec moves through specify, build and verify. Your tracker keeps the plan, who and when; Memex holds what is being built, why, and what done means.
Decisions, narrative, acceptance criteria
Once a Spec is created, the job in the specify phase is to extract and make every decision the implementation needs, and to update the narrative in line with the decisions you have made. From those decisions Memex creates acceptance criteria that match both the narrative and each individual decision.
You cycle through this loop, updating the narrative, making decisions, and adding or updating acceptance criteria, until you believe everything is well formed. Then you advance the Spec to the build phase.
Memex inspects the advancement. It checks that acceptance criteria exist and that the Spec is sufficiently well formed; if it is not, Memex recommends against moving. If any element has open comments, for example from a colleague's review, those comments are surfaced too, with the intent that you resolve them before the Spec moves to build.
Key output: a well-formed Spec, every decision resolved, acceptance criteria matching the narrative and each decision, open comments cleared.
Tasks, execution, issues, QA report
The build phase needs little human involvement beyond picking up the occasional piece of work. Memex works with your coding agent to agree a set of tasks and all the interdependencies between them, and those are written into Memex.
The agent then decides how to execute those tasks, using whatever tools it has available and any parallel sub-agents it thinks are appropriate, and it works through the set. When it hits issues or to-dos, work that still needs dealing with, or unexpected problems blocking execution, it does not swallow them the way a coding session normally would. It logs them back to Memex as issues associated with the Spec, where they materialise in the user interface for you to see.
When the build is finished, Memex produces a human-readable QA report and pushes it back into the Spec, then advances the Spec to the verify phase.
Key output: implemented tasks, any blockers logged as issues in the UI, and a human-readable QA report in the Spec.
The final control
The verify phase checks every acceptance criterion, the narrative, and every decision, to confirm that everything was implemented correctly. It also surfaces any outstanding issues and lets you decide how to resolve them. This is the critical final control that makes sure the work is actually done.
If you are already satisfied that every acceptance criterion has been met and is showing green in the user interface, you can move the Spec straight to done. Best practice, though, is to run the verify phase on every Spec, because it is the final form of verification, and then move the Spec to done.
Key output: every acceptance criterion, decision, and the narrative confirmed correct, outstanding issues resolved, and the Spec moved to done.
Features
Knowledge Graph
The knowledge graph is the memory that every Spec, decision, and standard feeds into. It exists in two forms.
- Standards, kept current: Standards are updated under your control and then referenced continually by Memex. As agents work, Memex registers drift: when a
search_memexrequest surfaces information that no longer matches the code, it is logged as drift and becomes a human decision to resolve. That feedback loop keeps the standards accurate over time instead of letting them rot. (See Drift Detection.) - Vector-indexed Specs and decisions: Every Spec and every decision is vector indexed in the Postgres database and returned to the coding agent whenever it calls the
search_memextool. The agent gets the full context of everything decided across every completed Spec, including the name of the person who did the work or made the decision, and when. Over time the agent can reach everything that has already been built and chosen, so past work informs new work automatically.
Drift Detection
Drift detection is the feature that makes Memex 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 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
candidatedecision 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 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.
- 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
- 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
Architecture
Tech Stack
| Layer | Technology | Details |
|---|---|---|
| Database | PostgreSQL 16 (pgvector) on Cloud SQL | Path-based tenant resolution; isolation enforced in middleware and the unified mutation path. Unauthorized access returns 404, never 403. |
| API + MCP Server | TypeScript (Hono) on Cloud Run | Single container serves both REST (/api/*) and MCP (/mcp). Real-time updates over SSE from a unified mutation bus. |
| Admin Frontend | React 19 + Vite + TypeScript | The React UI. Live spec board and dependency graph visualisation. |
| AI agent | Anthropic SDK + LangGraph | Direct Anthropic SDK on the server; LangGraph drives the in-UI agent. Bring your own keys. |
| Auth (humans) | Native JWT | Hand-rolled JWT + scrypt password hashing + email magic links via Postmark. No Firebase. |
| Auth (agents) | OAuth or MCP tokens | OAuth 2.1 for Claude; mxt_ MCP tokens for every other client. Both are hashed in the DB and resolved to the user at middleware. |
MCP Transport
Memex 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.
MCP Tools Reference
The 37 tools below are the complete surface any connected agent reaches via MCP. Each one is marked read-only, writes (changes data you can edit or restore), or deletes data (a hard delete that no tool brings back), matching the MCP annotations the server sends. Several tools act on one resource and take a verb argument that picks the operation. Your client's live tool list is always authoritative; this page was last checked against the server on 1 November 2026.
Writes stay inside the Memexes you are a member of. Before an agent calls a tool that deletes data, it should confirm with you.
Read (any phase)
- get_information(topic?) read-only. Reference documentation on Memex concepts (phases, ACs, milestones…). Call with no args for the topic index; call with topic='<slug>' for one topic's full body (session-init prompt is intentionally tiny).
- list_memexes() read-only. List the Memexes you have access to, grouped by namespace; call first when working across more than one.
- list_docs(memex?, docType?, statusIn?, tags?) read-only. List Specs with decision/task counts and lineage. Defaults to EVERY phase - draft, specify, build, verify, done - with archived the only exclusion, and superseded Specs included. Narrow with statusIn/docType/tags.
- get_doc(ref) read-only. Get a document with all sections, decisions, tasks, comments, blockers, plus its public URL.
- get(ref, view?, page?) read-only. Read by canonical ref. view: content (default), tests (AC digest), export (markdown), prompt (handoff, after orienting on a Spec or a phase transition; a milestone's plan prompt), roles, history, burnup (milestones). Verbs: content, tests, export, prompt, roles, history, burnup.
- list(of, ref?, readyOnly?, kind?, status?, type?, types?, mode?, memex?, all_memexes?, stage?, doc?, assignee?, cursor?, limit?) read-only. List by `of`: a Spec's tasks/acs/issues (sub-refs list the parent doc), comments, skills (all_memexes: every Memex; ask if names collide), milestones (not Done; stage filters), or drift (open Drift Inbox, paged). Verbs: tasks, acs, issues, comments, skills, milestones, drift.
- search_memex(memex?, query, kind?, includeArchived?, includeCurrentDoc?, limit?) read-only. Semantic + full-text search across Specs, Standards, docs, and Decisions in the active Memex; also finds a Spec by part of its title.
- search_issues(memex?, query, includeArchived?, limit?) read-only. Search Issues across the Memex (scoped to kind:issue): cross-spec discovery of a bug/todo registered on any Spec.
- facets(verb, memex?) read-only. Check which parts of your Standards apply to a piece of work: lists the topics they are tagged by. Cast them as the facetBallot on task create / decision(verb: 'create'); Memex surfaces the governing standard sections.
- get_skill(ref, working_spec_ref?, path?) read-only. Read one Skill: the verbatim SKILL.md body + a table-of-contents of its auxiliary files (no inline contents). Pass path to fetch one file (binary → signed URL, text → inline); working_spec_ref meters usage.
Draft and specify: Specs, sections, decisions, lifecycle
- create_doc(memex?, title, purpose?, docType?, decisions?, promoteFromTaskRef?, promoteFromIssueRef?) writes. Create a new Spec (or other docType); optional decisions seed, promoteFromTaskRef / promoteFromIssueRef preserves lineage.
- tag(verb, memex?, tag, newTag?) writes. Tag vocabulary (`scope::value` or flat). verb create: coin a tag; refuses a case-insensitive duplicate. verb rename (+ newTag): the new name lands on every carrying Spec, or nothing changes and the reason is stated. Verbs: create, rename.
- tag_delete(memex?, tag) deletes data. Delete a tag from the vocabulary; it is removed from every Spec that carried it, leaving those Specs otherwise untouched. Irreversible, one tag per call. Refused for a tag bound to a milestone.
- section(verb, ref, sectionType?, content?, clauses?, clauseFacets?, title?, description?, oldText?, newText?, replaceAll?) writes. A document's sections by verb. add (doc ref; standards: clauses[]+clauseFacets[]). update replaces the ENTIRE body; prefer edit: one oldText/newText pair, no body re-emission (replaceAll). retitle, soft delete, restore. Verbs: add, update, edit, retitle, delete, restore.
- clause(verb, ref, body?, position?, facets?, testability?) writes. A STANDARD's clauses by verb. add (section ref, body, facets; position? inserts): gets a cl-N. edit (cl-N): the body. delete: soft; the cl-N is never reused. restore: back in its old place. Verbs: add, edit, delete, restore.
- decision(verb, ref, title?, context?, status?, options?, resolution?, chosenOptionIndex?, reason?, facetBallot?) writes. A decision by verb. create (doc ref, title): status='candidate' for an agent-extracted one. update: edit in place, reopen, or restore. resolve: record the choice. approve/reject: a candidate. delete: soft. Verbs: create, update, delete, resolve, approve, reject.
- assess_spec(ref, mode, target?, codeGrounding?) writes. Run a deterministic Spec assessment: phase rubric, narrative freshness, comments survey, or consolidate.
- ground_spec(ref, codebase_present) writes. Mark a Spec code-grounded (decisions verified against current source); MCP-only, requires codebase_present. Stamps who/when as a verification badge.
- set_sensitive(ref, sensitive) writes. Flag a Spec as sensitive (contact someone before changing it) or clear the flag. Advisory only: blocks nothing; whoever sets it becomes the contact, and there is no reason field.
- spec(verb, ref, status?, from?, title?, tags?, removeTags?, supersededBy?, note?, reason?, refs?, after?, before?, top?) writes. Lifecycle by verb. update: status, title, tags (`from` guards). supersede (supersededBy; null clears). override (reason): done-gate. place (after|before|top). pause|unpause|proceed (reason): agents stop and ask first. Verbs: update, supersede, override, place, pause, unpause, proceed.
- milestone(verb, memex?, ref?, title?, owner?, assignees?, target?, tag?, references?, expectedRevision?, statement?, covers?, evidence?, specs?, spec?, top?, before?, after?, reason?, stage?) writes. Milestone writes: create (memex, title, owner, tag); update (title, owner, assignees, target, references); ac (edits withdraw acceptance; covers, evidence); order (all Specs); rank; archive; pause/unpause; reason. Verbs: create, update, ac, order, rank, archive, pause, unpause, reason.
Build: tasks, acceptance criteria, standards, issues, roles, Skills
- task(verb, ref, title?, description?, status?, acceptanceCriteria?, sectionRef?, servesAcs?, addBlockerRef?, removeBlockerRef?, facetBallot?) writes. A build-phase task by verb; resolve open decisions first. create (doc ref, title, description): name the ACs it serves (servesAcs), add a checklist. update (task ref): status, fields, servesAcs (replaces), blockers. Verbs: create, update.
- task_delete(ref) deletes data. Delete a task; also removes its blockers and dependencies.
- write_qa_report(ref, content, title?) writes. Persist a QA Report on a Spec at the build-to-verify hand-off - a reviewer-facing record of what this session changed: front-end, back-end, testing, gaps, deviations. Appends a dated version; never overwrites.
- standard(verb, ref?, observation?, decisionRef?, operations?, rationale?) writes. Evolve a Standard by verb. flag-drift: the rule is right, the code drifted. propose-change: the rule is wrong: clause edits land as a `plan_revision` comment. accept-change: apply an open proposal by its ref. Verbs: flag-drift, propose-change, accept-change.
- issue(verb, ref?, memex?, spec_ref?, title?, body?, type?, severity?, promote_to_spec?, resolution?) writes. A Spec's Issues (bugs/todos) by verb. register (spec_ref, title, body, type): without spec_ref it persists nothing: no silent default home. update: title/body/severity. resolve. convert-to-task (build). Verbs: register, update, resolve, convert-to-task.
- kick_task_to_issue(ref, reason) deletes data. 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.
- role(verb, ref, user?, role?) writes. Who holds what on a Spec. verb set (user, role?): editor or reviewer. assign (user?) / unassign (user). claim / unclaim: check the Spec out for this thread, or release it. Read with get(view: 'roles'). Verbs: set, assign, unassign, claim, unclaim.
- ac(verb, ref, kind?, statement?, parent_decision_ref?, decision_ref?) writes. An acceptance criterion by verb. create (Spec ref, kind, statement): scope, or implementation with parent_decision_ref. update (AC ref): the statement, refused once verified. link: add a parent decision. Verbs: create, update, link.
- ac_delete(ref) deletes data. Hard-delete an AC by ref; FKs cascade its parent links and task links. For accidents or duplicates: retire a considered criterion with ac_supersession(verb: 'propose') instead.
- ac_supersession(verb, ref, decision_ref?, proposed_statement?, rationale?) writes. Reverse a criterion on the record, by verb. propose (AC ref, decision_ref): changes nothing until accepted. accept (comment ref): rewrites it in place, same handle; no replacement retires it. reject: closes the proposal. Verbs: propose, accept, reject.
- provision_ac_emission(ref) writes. Provision AC emission for this Spec in one call: mints an ephemeral, spec-scoped key (session-only, never persist) and returns wiring guidance for the repo's test runners. No Settings detour; CI keys stay human-minted.
- ac_discontinue_events(ref, test_identifier, reason) deletes data. Hard-delete an orphaned test_identifier on an AC - a renamed test whose stale fail pins the AC red. Removes its emissions and summary, keeping a receipt of who, when, why and the commit. Reason required. Irreversible.
- skill(verb, memex?, ref?, skill_md?, capabilities?, files?, remove_files?) writes. Create, edit, delete, or restore a Skill: import SKILL.md files into a Memex. create: memex + skill_md (+ capabilities/files); edit: ref + skill_md/capabilities/files (new paths only); delete/restore: ref. Verbs: create, edit, delete, restore.
- skill_file(verb, ref, paths?, files?) deletes data. Remove or overwrite a Skill's auxiliary files. Irreversible: the old bytes are gone. delete: ref + paths; replace: ref + files whose paths already exist. Add a new path with skill(verb: "edit"). Verbs: delete, replace.
Comments and handoff to people
- comment(verb, ref, authorName?, content?, type?, referenceRef?, anchorOffset?, status?, resolution?, user?) writes. Comment by verb. add: on a section, decision or task; type=question asks the user, anchorOffset anchors it in a section. resolve: close one by ref. assign (user: a member) / unassign: set or clear its one owner. Verbs: add, resolve, assign, unassign.
- notify(destination, memex?, channelOrUser?, text, specRef?) writes. Message a human for an AI→human handoff. destination slack: as the current user via their connected Slack (channelOrUser required). destination discord: to the org's Discord webhook channel. Verbs: slack, discord.
Authentication
Auth Model
Memex has two authentication paths: one for agents, one for humans. Both resolve to the same multi-tenant account model.
Agents (MCP connections)
Claude connects with OAuth: it registers itself, you sign in to Memex in your browser and approve, and Claude receives a short-lived access token plus a refresh token that rotates on every use. Every other client sends an MCP token with the mxt_ prefix, created per device by the Memex installer. Either way the server hashes the credential, resolves it to you, and scopes every query and mutation to the Memexes you are a member of, at the middleware and unified mutation layer.
To disconnect, remove the Memex connector in your client. MCP tokens can also be revoked one at a time in Memex under Settings → Integrations → MCP Tokens, which cuts off that device immediately without affecting the others.
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. A connected agent can only ever act inside the Memexes its user belongs to, 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 (role, verb set). Roles are independent of assignment: a reviewer can still be assigned a Spec (role, verb assign) 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, MCP tokens, and org membership stay with humans. Phase transitions to done are a human call, never the agent's.