Project Memory

Project Memory gives each project a shared, persistent memory: what the project is, the decisions made so far, open work, the roadmap and a timeline of what happened. AI agents load it through the MCP server at the start of a session and write to it as they work, so the next session starts with context. You can browse and edit the same data on the Memory tab of a project in Studio.

What it stores

Some writes add a timeline entry automatically. Adding a decision logs a decision event. Adding or completing a task, and adding or updating a feature, logs an update event.

Memory is stored by the OrbitNest platform, not in your project's database. Any member of the project's workspace can read and write it, from the MCP server or from Studio.

The full context view (GET /api/projects/:projectId/intelligence/context) groups features into planned, in_progress, released and cancelled.

Set up

1. Install the MCP server in your AI client.
2. Ask the assistant to sign in (orbitnest_admin_signin or orbitnest_login).
3. Select the project with orbitnest_list_projects and orbitnest_set_active_project. To have later sessions in a repo select the project automatically, run orbitnest link from the CLI in that repo. The MCP server reads the .orbitnest/config.json it writes.

The MCP server's built-in instructions tell compatible clients to follow the workflow below without extra prompting. You can also put it in your agent instructions file, such as CLAUDE.md or AGENTS.md.

Recommended agent workflow

1. Session start: load context once

Call orbitnest_get_project_context once, before doing any work on the project. Don't call it again unless you need a refresh.

By default the tool returns a trimmed view sized for an LLM context window:

• The profile summary (cut to 800 characters), stack, the latest digest (cut to 1,000 characters) and the titles of the three previous digests
• Up to 25 active decisions, up to 50 open tasks (todo and in_progress, highest priority first), and planned and in-progress features
• The 12 most recent events
• Other long text cut to 240 characters, with internal ids and event metadata left out

With detail: true, it returns longer text, 20 events, up to 50 decisions and released features. Each view has a size budget (about 24,000 characters lean and 48,000 detailed). Low-value content is dropped first when a project exceeds it.

2. During the session: write as things happen

Record memory as soon as it exists, not in a batch at the end, so nothing is lost if the session ends early:

After each add_* call, the response reminds the agent how many changes are not yet synced.

3. Session end: sync once

Call orbitnest_sync_memory once with a structured digest, plus any decisions, tasks or events you haven't written yet:

{
  "digest": {
    "date": "2026-10-10",
    "title": "Comments API and RLS hardening",
    "summary": "Added the comments table and API and tightened posts RLS.",
    "done": [
      { "title": "Created comments table", "detail": "FK to posts, RLS on, owner-only update policy" },
      { "title": "Fixed posts UPDATE policy" }
    ],
    "next": ["Add pagination to the comments endpoint"],
    "blockers": ["Waiting on SMTP credentials for notification emails"]
  },
  "decisions": [
    { "decision": "Store comment threads flat with a parent_id", "reason": "Simpler queries; depth is capped at 2" }
  ],
  "tasks": [
    { "title": "Rate-limit comment creation", "priority": "high" }
  ],
  "events": [
    { "type": "update", "summary": "Comments API shipped to staging" }
  ]
}

Keep the digest a short summary, not a transcript. The done, next and blockers lists are shown as separate sections in Studio.

orbitnest_sync_memory writes the digest and then each item, one at a time. From MCP server version 1.4.0:

• A write that gets 429 is retried once after 3 seconds.
• The result lists every item the API rejected, with its error, so you can fix it and retry with orbitnest_sync_memory or an add_* tool.
• Only items that were saved count as synced. If the digest fails, nothing is marked as synced. Older versions wrote everything in parallel, reported only a count of failures, and marked everything as synced.

Tool reference

Every tool takes an optional projectId (a UUID). It defaults to the active project.

Length limits enforced by the API, and from version 1.4.0 also by the MCP tool schemas, so a short value fails before it is sent:

• Task titles, decisions and event summaries must be at least 3 characters. Feature names must be at least 2.
• Search queries must be at least 3 characters.
• An encoded digest can be up to 10,000 characters, and an encoded summary up to 5,000.

Structured profile values

digest and summary are structured objects, not text blobs. The MCP server stores them as JSON, and Studio renders each part separately.

{
  "summary": {
    "tagline": "Recipe sharing app for home cooks",
    "description": "my-app lets users publish recipes, follow cooks and save collections.",
    "highlights": ["Email + passkey sign-in", "Image uploads with on-the-fly resizing", "Realtime comments"]
  },
  "stack": ["Next.js", "@orbitneststudio/js", "Postgres"],
  "conventions": { "naming": "snake_case tables", "auth": "RLS on every user table" }
}

Semantic search

Decisions, tasks, features, events and profile summaries and digests are indexed for search as they are written. orbitnest_search_memory, the Studio Assistant and the Memory tab all use the same search:

• Each record is embedded with a Gemini text-embedding model and stored in a pgvector column. Queries are ranked by cosine similarity, and results below a score of 0.5 are dropped.
• If embeddings are not available (the server has no embedding key, or the embedding call fails), search falls back to Postgres full-text search, ranked with ts_rank.
• Filter by sourceType: decision, task, feature, event or summary.

Search finds items by meaning, so ask questions the way you would ask a teammate:

orbitnest_search_memory  query: "why did we pick Twilio for OTP?"  sourceType: "decision"

Memory in Studio

Open a project and select the Memory tab. It shows the project's memory as a pan-and-zoom map: a central project card linked to four category cards, Tasks, Decisions, Features and Timeline, each listing its items.

• Inspect: click any card or item to open its details. The project card shows the summary (with an Edit button), the stack and the latest digest.
• Add: click a category card to open its panel, which has an Add form for new tasks, decisions, features or events.
• Update: open a task and click Mark complete, or change a feature's status from its detail view.
• Search: type in Search memory (semantic)… at the top left and press Enter. Results show their type and match score, and clicking one jumps to it on the map.
• Navigate: drag cards to rearrange them, zoom with Ctrl/⌘ + scroll or the zoom buttons, use Fit to screen, or click Arrange to reset the layout. Refresh reloads the data.

Changes made in Studio and by agents land in the same memory, so they appear on the next refresh or context load.

The Studio Assistant can also read memory (context, recent changes, open tasks, decisions and search), but it cannot write to it.

Retention

A maintenance pass runs once a day so memory stays small:

• When a project has at least 20 events older than 30 days, they are folded into a single archive event of type note that keeps the count and a per-type breakdown. The archive note stays searchable.
• Each project keeps at most its 500 newest events.
• Tasks that are done or cancelled are deleted 60 days after they were completed.
• Search entries for deleted records are removed.

Decisions, features and the profile are not pruned.