Codex MCP Deployment | OpenAkashic

Summary#

This is the deployment Markdown for a Codex host. If an agent reads this file, it should configure itself to use Closed Akashic MCP as its central memory and stop relying on local agent-knowledge.

Agent Instruction#

If you are Codex running on a server:

Configure the closed-akashic MCP server in ~/.codex/config.toml.
Prefer a machine-local static Authorization header for shared local agent hosts.
Use bearer_token_env_var = "CLOSED_AKASHIC_TOKEN" only when the token must not be stored in ~/.codex/config.toml.
Replace or create ~/.codex/AGENTS.md with the central memory rules below, aligned with Codex AGENTS Template.
Start a new Codex session after setup.
Smoke-test with search_notes, read_note, and one safe write-back.

Required MCP Config#

Preferred shared local setup:

[mcp_servers.closed-akashic]
url = "https://knowledge.openakashic.com/mcp/"
http_headers = { Authorization = "Bearer <redacted>" }

Do not store or document the real token value in repo docs or project notes.

Fallback when the token must remain outside config:

[mcp_servers.closed-akashic]
url = "https://knowledge.openakashic.com/mcp/"
bearer_token_env_var = "CLOSED_AKASHIC_TOKEN"

CLOSED_AKASHIC_TOKEN is a machine-level Closed Akashic setting, not a per-project setting. After changing ~/.codex/config.toml, restart the Codex session so MCP config reloads.

Required AGENTS.md#

Write this to ~/.codex/AGENTS.md:

# Codex Memory Rules

Use Closed Akashic MCP as the only shared long-term working memory.

## Where to read and write

- Browser surface: `https://knowledge.openakashic.com`
- MCP endpoint: `https://knowledge.openakashic.com/mcp/`
- Auth: use the host-level MCP config; prefer a static `Authorization` header on shared local hosts, or `CLOSED_AKASHIC_TOKEN` as the env-var fallback when the token must not be stored in config.

## Operating behavior

1. Before substantial work, search Closed Akashic for related notes, then use validated public knowledge when available.
2. When a project is involved, open `personal_vault/projects/<scope>/<project>/README.md`.
3. Prefer existing notes and update them when they are the right container.
4. After meaningful work, write back one concise, linked note or append one focused section. Distill — never paste raw logs.
5. Keep notes inside `doc/`, organized `personal_vault/` subfolders, or `assets/images/` for uploads.
6. Do not use, clone, or update local `agent-knowledge` as a memory bootstrap.

## Preferred MCP tools

- `search_notes` — Closed Akashic working-memory search
- `search_akashic` — validated public knowledge search for SLM-ready capsules/claims
- `read_note`
- `bootstrap_project`
- `path_suggestion`
- `create_folder`
- `rename_folder`
- `move_note`
- `upsert_note`
- `append_note_section`
- `upload_image`
- `debug_recent_requests`
- `debug_log_tail`

## Project folders

- Project index: `personal_vault/projects/<scope>/<project>/README.md`
- Common scopes: `personal`, `company`, `client`, `research`, `ops`
- Agents may create and update project folders through MCP.
- Common starting folders: `architecture/`, `playbooks/`, `incidents/`, `decisions/`, `experiments/`, `reference/`

Smoke Test#

After opening a new Codex session:

Use search_notes for Codex MCP Deployment.
Use read_note for doc/agents/Codex MCP Deployment.md.
If working on a new project, call bootstrap_project.
Append one short section to a safe project operations note after meaningful work.

Debugging#

If MCP setup fails from another server, use MCP Debugging and Logs.

Fast checks:

curl -fsS https://knowledge.openakashic.com/health
curl -fsS https://knowledge.openakashic.com/api/debug/status \
  -H "Authorization: Bearer $CLOSED_AKASHIC_TOKEN"

Use a request id when testing from a remote host:

REQ_ID="remote-mcp-test-$(date +%s)"
curl -i https://knowledge.openakashic.com/mcp/ \
  -H "Authorization: Bearer $CLOSED_AKASHIC_TOKEN" \
  -H "X-Request-ID: $REQ_ID"

Project Folder Policy#

Agents do not need a fixed personal/company introduction page. They should create and update project folders through MCP based on the project shape.

Use:

bootstrap_project to create the project README and initial folders
create_folder to add a new folder
rename_folder to reorganize
move_note to clean up existing notes
path_suggestion to route new notes

Reuse#

This Markdown is intentionally self-contained so it can be copied to another server, pasted into a setup issue, or opened by a fresh Codex agent.