Overview

memex.ai is the strategy, decision, and knowledge layer for AI-native software teams. It provides a shared graph that both humans and AI 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 four interconnected layers: strategies (the objectives), decisions (the choices that shape implementation), work items (a dependency-aware execution graph), and blueprints (scoped, prescriptive knowledge 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 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 strategy Define an objective — the full context that makes every downstream choice intelligible. Add decisions, scope work items with explicit dependencies, and write blueprints. 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 context, check decisions and dependencies, and produce execution plans. You review and approve. They implement. Drift detection and decision extraction start working from day one — automatically.

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

Strategies

A strategy is the top-level container 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.

Strategies are documents, not records. Their content lives in ordered sections — purpose, vision, context, approach, risks, and custom sections. Each section is independently addressable: agents edit one section at a time (sending only 200-500 tokens per edit), and humans can comment on individual sections during review.

Lifecycle:

• DRAFT — Initial state. Content is being shaped. Agents can create a draft via create_strategy_draft.
• ACTIVE — Published and driving work. Decisions, work items, and blueprints are linked.
• ARCHIVED — Completed or superseded. Still queryable for historical context.

Tags: Strategies support freeform tags for categorisation — priority:high, team:platform, etc. Convention-based namespacing keeps things queryable without rigid schema. If a tag pattern solidifies into something every strategy needs, it graduates to a first-class field.

Section-level commenting: Reviewers can add comments to individual sections. Comments can be resolved by authors. The strategy detail URL is shareable — paste it into Slack and see the title, status, 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 an ID, status, options considered, and rationale.

Sequential IDs: Decisions are numbered per strategy — D1, D2, D3, etc. This keeps references human-readable in conversation ("see D3 on the auth strategy") while UUIDs handle cross-strategy 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:

• OPEN — A decision that needs to be made. Open decisions block dependent work items, preventing agents from building against unresolved ambiguity.
• LEANING — A preference has emerged but the decision isn't final. Indicates direction without commitment — useful for unblocking parallel work while the final call is pending.
• RESOLVED — A decision that has been made. Resolution records the chosen option, the rationale, and which options were rejected. Resolved decisions constrain downstream implementation and inform blueprints.

Re-opening decisions: When priorities shift or new information surfaces, you can re-open a resolved decision via reopen_decision. The system traces the impact — marking affected work items as potentially stale and flagging related blueprints for review. Use get_decision_impact to see the full cascade before re-opening.

Work Items

Work items in memex.ai are not a flat backlog — they form a directed acyclic graph (DAG). Each work item has a goal, acceptance criteria, and explicit dependencies on both other work items and decisions.

Sequential IDs: Like decisions, work items are numbered per strategy — WI-1, WI-2, WI-3, etc. Human-readable in conversation, UUIDs internally for cross-strategy dependencies.

The dependency graph means the system always knows what's ready to start, what's blocked, and why. Agents call get_ready_work_items and the system returns only those with all dependencies met and all blocking decisions resolved. Use check_dependencies to see met vs. blocked dependencies, and get_dependents to see what a work item unblocks.

Status lifecycle:

• NOT STARTED — Created, waiting for dependencies or pickup
• BLOCKED — Dependencies not met or blocking decisions unresolved
• IN PROGRESS — Actively being worked on, execution plan submitted
• COMPLETE — Finished, which may unblock downstream work items

Tags: Work items support freeform tags for type (type:verify, type:release, type:gate), execution mode (agent-only, human-only, paired), and any other classification.

Acceptance criteria: Each work item has structured acceptance criteria — a list of conditions that must be met for the item to be considered complete. These are checkable (done/not done) and give agents clear targets.

Execution plans: Before coding, agents call submit_execution_plan with the files to modify, dependency flow, and any conflicts found. This grounds the implementation in the strategy's decisions and blueprints, and gives humans a chance to review the approach before code is written. Plans can be approved or superseded.

Blueprints

Blueprints are scoped, prescriptive instructions — 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 can reliably consume and act on.

Account-level, not per-strategy. Blueprints live at the account level and are linked to strategies via a many-to-many relationship. A "deployment" blueprint might be relevant to five different strategies — it exists once, linked to all of them. This avoids duplicating knowledge when multiple strategies share the same domain concerns.

Domain-scoped: Each blueprint covers a specific domain — "deployment", "testing", "auth", etc. The domain is unique per account: one blueprint per domain, one source of truth.

Every blueprint traces to the decisions that produced it. When a decision is re-opened or a work item changes something a blueprint covers, the system flags the blueprint for review. Use get_blueprints_affected_by_decision to see the cascade. This is how memex.ai prevents knowledge from rotting silently.

How agents use blueprints: When an agent picks up a work item, it calls get_blueprints_for_work_item to load the relevant scoped knowledge. The blueprints tell the agent which conventions to follow, which patterns to avoid, and which verification steps are required — all grounded in actual decisions, not guesses. Agents can also call update_blueprint to keep blueprints current as implementations evolve.

Drift status:

• CURRENT — Blueprint is up to date and aligned with the codebase and decisions
• DRIFT DETECTED — Something has changed that may make this blueprint inaccurate. Needs human review.
• STALE — Blueprint is significantly out of date. Multiple drift events or extended time since last verification.
• UNDER REVIEW — Blueprint is actively being updated in response to drift or new decisions.

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 blueprints and reality through four mechanisms:

• Agent-reported drift: During execution planning, agents compare what they find in the codebase against what the blueprint prescribes. If there's a mismatch, the agent flags it with evidence — "code says X, blueprint says Y."
• Decision-triggered drift: When a decision is resolved or re-opened, the system automatically identifies which blueprints are affected and marks them for review. A new auth decision, for example, flags the auth blueprint.
• Implementation-triggered drift: When a work item is completed, the system prompts a review of any blueprints that cover the modified domain. The implementation may have introduced patterns or constraints not yet reflected in the blueprint.
• Scheduled audits: Continuous, automated comparison of blueprints against the current state. Not a quarterly review — an ongoing process that surfaces drift before it causes problems.

Decision Extraction

Nobody will log decisions manually — that's a well-known failure mode of every knowledge management system. memex.ai solves this with passive decision extraction.

How it works:

• Passive extraction: When agent sessions end, the system analyses the conversation to surface decisions that were made — explicitly or implicitly.
• Decision bundles: Extracted decisions are batched into bundles with a summary, rationale, and link to the source conversation. Think of it like a merge request, but for decisions.
• Review flow: Humans review decision bundles with progressive disclosure — approve, reject, or flag individual decisions. No need to read the entire conversation.
• Merge into the graph: Approved decisions become first-class objects in the decision graph, complete with provenance. They can now block work items, constrain implementations, and trigger blueprint reviews.

Human-Machine Collaboration

memex.ai is designed for the team you actually have — humans and AI 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:

• Strategy 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 work items
• 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 following tools are available to any connected agent via MCP. They form the complete API surface for interacting with the memex.ai decision graph.

Strategy Tools

• list_strategies() Returns all strategies with a summary of their status, decision counts, and work item progress.
• get_strategy(id) Returns the full strategy document — all sections in order, plus decisions, work items, and linked blueprints.
• get_strategy_status(id) Returns a lightweight status summary — open decision count, work item progress, drift alerts.
• create_strategy_draft(title, sections) Creates a new strategy in draft status with initial sections (purpose, vision, context, approach, risks).
• update_section(section_id, content) Updates a single section's content. Agents edit one section at a time — small, targeted writes.
• add_section(strategy_id, type, content) Adds a new section to a strategy. Supports custom section types beyond the standard set.
• remove_section(section_id) Removes a section from a strategy document.
• publish_strategy(id) Transitions a strategy from draft to active. Requires at least a purpose section.
• promote_work_item(wi_id) Elevates a work item to its own strategy when scope warrants independent tracking.

Decision Tools

• get_decision(id) Returns a decision's status, options with trade-offs, chosen option (if resolved), and rationale.
• get_decisions(strategy_id) Returns all decisions for a strategy with status filters. Shows D1, D2, ... sequence.
• create_decision(strategy_id, question, options) Creates a new open decision with a question and options (each with label, description, trade-offs).
• resolve_decision(id, choice, rationale) Resolves a decision. Records the choice, rationale, and rejected options. Cascades to dependent work items and blueprints.
• reopen_decision(id, reason) Re-opens a resolved decision with a reason. Cascades staleness to downstream items and flags affected blueprints.
• get_decision_impact(id) Returns the full impact cascade — which work items are blocked, which blueprints would be affected by re-opening.

Work Item Tools

• get_work_item(id) Returns full work item detail — goal, acceptance criteria, status, dependencies, tags, and execution plan.
• get_ready_work_items(strategy_id?) Returns work items with all dependencies met that can start immediately. Optionally scoped to a strategy.
• check_dependencies(wi_id) Returns met vs. blocked dependencies for a work item, including cross-strategy work item and decision dependencies.
• get_dependents(wi_id) Returns which work items depend on this one — what completing it would unblock.
• update_work_item_status(wi_id, status) Transitions a work item's status (not_started, blocked, in_progress, complete). Triggers downstream dependency checks.
• submit_execution_plan(wi_id, plan) Submits an execution plan with files to modify, dependency flow, and conflicts found. Grounds the approach before coding begins.
• get_execution_plan(wi_id) Returns the current execution plan for a work item, including approval status.

Blueprint Tools

• get_blueprint(domain) Returns the scoped blueprint for a domain (e.g., "auth", "testing", "deployment") with prescriptive instructions.
• get_blueprints_for_work_item(wi_id) Returns which blueprints are relevant for a given work item, so agents load the right context.
• flag_blueprint_drift(id, evidence) Flags a blueprint as drifted with evidence — "code says X, blueprint says Y." Creates a drift event.
• get_blueprints_affected_by_decision(decision_id) Returns which blueprints would be affected by resolving or re-opening a decision.
• update_blueprint(domain, content) Updates a blueprint's content. Resets status to current and records the update in the activity log.

Assignment Tools

• assign_to_strategy(strategy_id, user_id, role) Assigns a user to a strategy with a role (lead or contributor).
• unassign_from_strategy(strategy_id, user_id) Removes a user's assignment from a strategy.
• assign_to_work_item(wi_id, user_id, role) Assigns a user to a work item with a role (lead or assignee).
• unassign_from_work_item(wi_id, user_id) Removes a user's assignment from a work item.
• get_my_strategies() Returns all strategies assigned to the current user, grouped by role.
• get_my_work_items() Returns all work items assigned to the current user with status and dependency info.
• get_assignments(strategy_id?) Returns all assignments, optionally scoped to a strategy. Shows who's working on what.

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, looks up the api_keys table, resolves to account_id, and sets row-level security on the database connection. The key's label (e.g., "claude-code", "cursor", "ci-agent") is recorded in the activity log for audit.

Keys can be revoked without affecting other keys on the same account. The last_used_at timestamp lets admins see which keys are active.

Humans (React admin)

The server verifies the JWT with Firebase Admin SDK, extracts the auth provider ID, looks up the users table to get user_id and account_id, and proceeds. The user's role (owner, admin, member) determines their permissions in the admin UI.

Permissions

The permission model defines what each role can do across the platform:

Agents can do most operational work — resolving decisions, updating work items, flagging drift, submitting execution plans — but cannot manage the account itself (users, API keys, strategy lifecycle).

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 — v20 or later (TypeScript runtime)
• PostgreSQL — v17 or later (the decision graph, work item DAG, blueprint storage, and row-level security for multi-tenancy)
• Firebase project — For human authentication (email/password + Google SSO). Agents authenticate via API keys and do not require Firebase.
• LLM API access — For decision extraction and drift detection features (bring your own API keys)

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:

Once running, point your agent's MCP configuration to https://your-server:3000/mcp. The React admin connects to the same server on /api/*. API keys (with mk_ prefix) are generated from the admin Settings page.