# Projects guide

Create personal project workspaces, manage memory associations, track TODOs and decisions, and scope agent context.

- Canonical: https://docs.xmemo.dev/docs/guides/projects
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 28cb8335d9b373a35b707cd026f121200119d72accc13546f0be91327d590fa7
- Edition-Digest: adfe9dc8d0e982dc671a2232a8953bd58a8d4e1d0528049c55439c2298e50f00
- Source-Revision: sha256:192851794c728ed3868a5be3be886563c1566aa6aec82e2a9d21109e443f6368

## User goal

Establish a dedicated project workspace to organize contextual memories, track operational decisions and active tasks, retrieve focused project context in connected agents, and verify that removing project associations leaves core personal memories intact.

## Availability and prerequisites

Project Workspaces are available across all personal accounts in the Memory Console at https://xmemo.dev/me#projects and through supported MCP client profiles:

- Personal boundary: Projects are strictly personal only today; attempting to create a project with team_id is rejected by the server (HTTP 400). Documentation makes no Team project promise.
- Uncapped quotas: Workspace creation is not constrained by numeric plan quotas or artificial project limits. Accounts provision workspaces as needed.
- Partitioned view: The Attention Needed view and Knowledge vs Working memory partitions operate if enabled for your account (the convergence evaluation mode defaults to off).
- Agent connectivity: Connected agents access project tools matching their client profile as contracted in config/mcp-documentation-contract.json.

## 1. Navigate to Projects in Memory Console

Log in to your personal dashboard and open https://xmemo.dev/me#projects. In the left navigation, select the Workspace section and click Projects. The panel header announces "Browse project workspaces, context, and project memories." and displays top-level metrics for Total Projects, Active, Attention Needed, and Archived.

```text
https://xmemo.dev/me#projects
Workspace -> Projects -> Total Projects (0) | Active (0) | Attention Needed (—) | Archived (0)
```

## 2. Provision a new personal project workspace

Click Create New Project in the top action area to open the workspace modal:

- Project Name: Enter a descriptive project name (e.g. "Incident Response Automation"). The field indicates "Required, 1-128 characters." and validates against control characters and path separators (/ or \).
- Project Identifier Preview: Review the preview identifier (#incident-response-automation). The helper confirms: "Non-authoritative preview. The backend server assigns the authoritative project key."
- Description: Optionally enter a scope charter up to 2000 characters (e.g. "Operational runbooks, triage checklists, and automated incident response workflows.").
- Submission: Click Create Project. The server assigns the canonical identifier and opens the project detail view.

## 3. Associate memories, TODOs, and decisions

Once the workspace is provisioned, populate it with scoped context, pending tasks, and architectural decisions:

- Associate a memory: Write a synthetic operational runbook memory scoped to the project (scope: "incident-response-automation"): "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts."
- Record a TODO: In the project detail view or via an agent, add a task: "Draft post-incident review template for payment gateway timeouts."
- Record a decision: Log an architectural decision: "Use PagerDuty webhook adapter for primary incident ingestion."
- Inspect hero metrics: The hero bar reflects live aggregates: Memories: 1, Open TODOs: 1, Decisions: 1.

```ts
await client.remember(
  "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts.",
  {
    path: "projects/incident-response-automation/runbooks/p0-escalation",
    scope: "incident-response-automation",
  },
);
```

## 4. Verify agent contextual recall

Connect an authorized agent client to verify that project retrieval returns the scoped records without cross-project noise:

- Cursor or Ordinary Full: Agents invoke get_project_context(project_id="incident-response-automation") to retrieve active memories, pending TODOs, and recorded decisions.
- ChatGPT or Generic Public: Agents invoke get_project_summary(project_id="incident-response-automation") or open_project_workspace to inspect summary status.
- ChatGPT in-chat widget: The in-chat interactive widget opened by open_project_workspace provides inline task cards directly inside the conversation; it is distinct from the full web Memory Console at https://xmemo.dev/me#projects.

```json
{
  "project_id": "incident-response-automation",
  "status": "active",
  "memories_count": 1,
  "open_todos": 1,
  "decisions": 1,
  "summary": "Operational runbooks, triage checklists, and automated incident response workflows."
}
```

## 5. Disassociate memory and verify non-destructive removal

Verify that removing a project memory unlinks the workspace association while preserving the underlying personal memory record:

- Open memory drawer: In the project memory list, select the operational runbook item to reveal the detail drawer.
- Initiate removal: Click Remove from Project in the drawer actions.
- Confirm disassociation: The modal opens with header "Remove from Project" and subtitle "This memory will be disassociated from this project workspace." Note the warning: "The memory content remains in your personal memory archive, but will no longer appear in this project context."
- Execute confirmation: Click Remove. The project memory count decrements to 0.
- Verify global persistence: Navigate to your personal memory archive (/me#memory) and confirm the runbook memory remains intact and retrievable.

## Observable result

Upon completing this workflow, your workspace demonstrates full operational isolation:

- Workspace status: The project is listed under Active projects with canonical slug #incident-response-automation.
- Contextual isolation: Connected agents query project context and receive scoped facts without contamination from unrelated projects.
- Data safety: Unlinking memory records from a workspace successfully decrements project aggregates while retaining personal memory records permanently in your archive.

## What agents can access

Agent tool availability depends strictly on the configured client profile in config/mcp-documentation-contract.json:

- chatgpt-public, generic-public, and public-only profiles: Expose project, get_project_summary, and open_project_workspace.
- claude-plugin profile: Exposes project and get_project_context.
- cursor-plugin and ordinary-full profiles: Expose get_project_context, update_project_todo, and update_project_decision.
- Profile boundaries: Other client profiles do not expose project tools. Attempting to call uncontracted tools will result in tool discovery rejections.

## Sharing and lifecycle boundaries

Project Workspaces enforce explicit operational and data boundaries:

- Personal boundary: All workspaces are personal only today. Team workspaces are not supported and requests supplying team_id fail validation.
- Lifecycle states: The memory explorer categorizes records into Active, Superseded, Expired, and Archived statuses.
- Curation partitions: If enabled for your account, workspaces offer Knowledge and Working memory partitions. The Knowledge partition holds persistent conventions; the Working partition stores transient session state.
- Distinction from Knowledge Bases: Project partitions categorize conversational episodic memories. In contrast, Knowledge Bases provide formal, versioned document management with multi-revision snapshots. For curated documentation, refer to /docs/concepts/knowledge-bases.
- Quota boundary: Personal project workspaces have no numeric quotas.

## Failure recovery

Common edge cases and recovery actions:

- Duplicate project name (HTTP 409): The server rejects duplicate project names with "A project with this name or identifier already exists in your workspace." Supply a distinct project name.
- Invalid project name (HTTP 400): Project names cannot contain slashes (/ or \), exceed 128 characters, or use reserved tokens (_project, ., ..). Correct the name in the creation dialog.
- Client profile tool mismatch: If an agent cannot find get_project_context, verify the active client profile. The chatgpt-public profile exposes get_project_summary, while get_project_context is exposed under cursor-plugin and ordinary-full.
- Version conflict (HTTP 409): If another session modifies the project or memory concurrently, the drawer displays "Modified elsewhere, please reload" alongside a Reload button. Click Reload to refresh state.

## Related reference

For complementary capabilities and technical references, explore:

- Projects Concept Reference: Architectural details and scoping conventions at /docs/concepts/projects.
- Memory Console Guide: Complete console walkthrough at /docs/guides/memory-console.
- Knowledge Bases Guide: Curated reference documentation management at /docs/concepts/knowledge-bases.
- Projects REST API: Authenticated programmatic endpoints at /docs/api/projects.

## ChatGPT user

Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.

Connect the hosted XMemo MCP server through the ChatGPT/OpenAI app OAuth flow, then approve the memory:read and memory:write grant for your XMemo account.

Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.

If OAuth fails or tools do not appear, sign out of the MCP server in the host app, reconnect the XMemo server URL, and retry before creating direct tokens.

## Copilot / Codex developer

Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.

Use OAuth for VS Code / GitHub Copilot and Gemini CLI when available. For Copilot CLI, Codex, Cursor, or other direct MCP clients, keep XMEMO_KEY in the local environment or secret store and set a stable XMEMO_AGENT_INSTANCE_ID.

Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.

If recalls are empty, verify the selected MCP config path, the XMEMO_KEY environment variable for direct clients, and any stale OAuth credential in the host app.

## Team / enterprise pilot owner

Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.

Create or enter the protected XMemo workspace, invite approved users, then connect each client through OAuth or a scoped direct credential according to the readiness badges.

Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.

If a member cannot connect, check role permissions, OAuth approval, client readiness status, and support guidance before issuing a new token.

## Autonomous agent operator

Let headless or scheduled agents record progress, retrieve prior decisions, and keep a stable non-secret instance identity.

Fetch /api/v1/mcp/config/autonomous-agent. Prefer auth_modes.oauth when the runner supports OAuth + custom headers; use auth_modes.xmemo_key with XMEMO_KEY from a secret store only for fully headless runners.

Run one synthetic task that writes progress to XMemo, restart the runner, and confirm it recalls that progress using the same XMEMO_AGENT_INSTANCE_ID.

If attribution changes or recalls split across instances, persist XMEMO_AGENT_INSTANCE_ID outside git and verify the runner is not regenerating it on every start.