Real dashboard UI with synthetic Atlas project data. No private Vault content is shown.
\n\n## Quick start\n\nThis is the shortest path to persistent memory for Claude Code, Codex, and other MCP\nclients. The guided installer creates the local service, Obsidian-compatible Vault,\ndashboard, MCP registrations, and agent skills together.\n\n### Requirements\n\n- macOS or Linux\n- Python 3.12 or newer\n- [`uv`](https://docs.astral.sh/uv/)\n- Claude Code or Codex for the managed client integrations\n- Optional: [Obsidian](https://obsidian.md/) for browsing the Markdown Vault\n- Optional: [Ollama](https://ollama.com/) for semantic retrieval\n\n### 1. Install\n\n```shell\nuv tool install global-memory-mcp\n```\n\nTo install the latest unreleased source, use\n`uv tool install git+https://github.com/ozankasikci/global-agent-memory.git`. For a\nlocal checkout, use `uv tool install .`.\n\n### 2. Run guided setup\n\n```shell\nglobal-memory setup\n```\n\nSetup shows one plan and asks once before it changes anything. It initializes the local\nVault, creates the protected token, detects Claude Code and Codex, installs their MCP\nintegrations and skills, verifies healthy clients, and opens the dashboard. Opening the\ndashboard starts its authenticated localhost server on demand. The command is\nidempotent, so running it again repairs or updates managed components without replacing\nunrelated client configuration.\n\nUse flags when you need a non-default setup:\n\n```shell\n# Non-interactive installation\nglobal-memory setup --yes\n\n# Choose a different Vault on first setup\nglobal-memory setup --vault \"$HOME/Memory\"\n\n# Install only one client, or no client yet\nglobal-memory setup --clients claude-code\nglobal-memory setup --clients none\n\n# Optional: install an always-on native service for live watching and shared indexing\nglobal-memory setup --service\n\n# Preview without changing files or services\nglobal-memory setup --dry-run\n```\n\n### 3. Use the installed agent shortcuts\n\nSetup installs five basic shortcuts for each detected client:\n\n| Shortcut | Purpose |\n| --- | --- |\n| `gam-context` | Load project-aware context for a task |\n| `gam-search` | Find a decision, fact, error, convention, or solution |\n| `gam-remember` | Propose explicitly supplied durable knowledge as a candidate |\n| `gam-review` | Show the candidate queue without changing it |\n| `gam-dashboard` | Open the authenticated dashboard |\n\nIn Claude Code, invoke them directly, for example `/gam-context fix the upload retry bug`.\nIn Codex, type `/skills` and choose one, or mention it directly, for example\n`$gam-context fix the upload retry bug`.\n\n### 4. Open the dashboard again\n\n```shell\nglobal-memory dashboard\n```\n\nYou can also ask a connected agent:\n\n> Open the Global Agent Memory dashboard.\n\nThe agent calls `memory_dashboard_open` and opens the same authenticated local\ndashboard.\n\n### Manual installation and repair\n\nThe individual commands remain available for advanced setups and troubleshooting:\n\n```shell\nglobal-memory init --vault \"$HOME/Documents/Global Agent Memory\"\nglobal-memory daemon install-service --kind launchd # use systemd on Linux\nglobal-memory integrations install all\nglobal-memory integrations verify all\nglobal-memory doctor\n```\n\n## Using it with an agent\n\nAfter integration, you normally describe your intent instead of running memory commands\nmanually.\n\n### Retrieve context before work\n\n> Before you start, load the relevant memory for this project and summarize the\n> conventions and recent decisions.\n\n### Propose a durable memory\n\n> Remember that production ARM64 binaries must be built locally and uploaded to the\n> server. Add it as a project convention with the deployment discussion as evidence.\n\nThe agent creates a candidate. Nothing becomes active until it is approved.\n\n### Update existing knowledge\n\n> Find the deployment memory and update it with the new health-check command. Do not\n> create a duplicate.\n\n### Open the review surface\n\n> Open the memory dashboard so I can review the candidates.\n\nThe shared integration skill teaches supported agents when to retrieve, propose, update,\nand avoid duplicating memory.\n\n## Obsidian Vault\n\nThe configured Obsidian Vault is the human-readable, durable source of truth—not an\nexport of an opaque database. Every managed memory is a normal Markdown file with YAML\nproperties, a stable memory ID, lifecycle metadata, and project-aware links.\n\nInitialization adds an Obsidian workspace without replacing your existing files:\n\n- templates for decisions, facts, solutions, conventions, preferences, entities,\n references, session summaries, and project overviews;\n- native Bases views for the candidate review queue, active knowledge, recent updates,\n decisions by project, verified solutions, and lifecycle history;\n- project overview hubs that embed project memories and remain stable as notes move\n through candidate, active, rejected, superseded, or archived folders;\n- wikilinks and reciprocal supersession links for backlinks and graph navigation;\n- request-time synchronization, so ordinary content and descriptive-property edits made\n in Obsidian become searchable without a background service;\n- optional watcher synchronization for immediate indexing when the background service\n is enabled.\n\nObsidian is optional: the same Markdown remains readable and editable with any text\neditor. Lifecycle and access-policy changes should still go through the dashboard, MCP,\nor CLI so validation, optimistic concurrency, and audit records remain intact.\n\n## Dashboard\n\nThe authenticated dashboard is the owner control plane for:\n\n- project overview and recent project activity;\n- one-at-a-time candidate review and editing;\n- duplicate and conflict comparison;\n- memory search and lifecycle management;\n- Standard, Protected, and Sealed classification;\n- access-request approval and active-grant revocation;\n- sealed-memory owner unlocks with audit records;\n- project switching, system health, reindexing, and backups;\n- opening canonical Markdown in Obsidian or the local file viewer.\n\n\n\nCandidate review keeps evidence and conflicts visible before an owner approves durable memory.
\n\nDashboard launch URLs expire after 60 seconds, can be exchanged only once, and create a\nlocal HttpOnly session. Do not share a launch URL.\n\n## Memory visibility and access\n\n| Level | Default agent behavior | Owner control |\n| ------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |\n| **Standard** | Included in ordinary scoped retrieval | Normal candidate and lifecycle review |\n| **Protected** | Excluded from default results; an agent receives only a neutral relevance signal | Owner selects exact memories, permission, duration, policy, and eligible projects |\n| **Sealed** | Body is not indexed or returned through agent tools | One owner-unlocked dashboard view; every access is audited |\n\nProtected grants are scoped by purpose, project, agent, permission, exact memory IDs,\nand duration. Owners may downgrade a request but never elevate it. Agents may request\nand poll for access, but they cannot approve, deny, or revoke grants.\n\n> [!IMPORTANT]\n>\n> Protected and Sealed memory are not secret managers. Never store passwords,\n> credentials, private keys, API keys, or bearer tokens in Global Agent Memory.\n\n## How it works\n\n```mermaid\nflowchart LR\n A[Claude Code] -->|stdio MCP| H[Hybrid MCP runtime]\n B[Codex] -->|stdio MCP| H\n C[CLI] -->|MCP| H\n\n H -->|daemonless default| E[Application and domain services]\n H -.->|optional localhost daemon| D[Watcher, shared indexing, dashboard]\n D --> E\n E --> V[Markdown Vault