doc/agent.md

Agent Guide

Codex, Cursor, OpenCode and similar agents should treat Closed Akashic as a persistent working memory, not as a one-shot retrieval dump. The intended access path is remote MCP and authenticated API access to the main server, so agents on other machines can use

Summary

Codex, Cursor, OpenCode and similar agents should treat Closed Akashic as a persistent working memory, not as a one-shot retrieval dump.

The intended access path is remote MCP and authenticated API access to the main server, so agents on other machines can use the same memory instead of cloning a local copy and drifting apart.

Core Model

Closed Akashic sits between raw work and future work.

  • Raw sources stay in repos, logs, docs, tickets, recordings, and external references.
  • Closed Akashic stores the distilled reusable knowledge as short linked markdown notes.
  • Agents should read before acting and write back after meaningful work.

The goal is compounding memory. Useful context should survive past one chat session.

Agent Contract

Every agent using Closed Akashic should follow these rules:

  1. Search memory before starting substantial work.
  2. Prefer existing notes over inventing new parallel explanations.
  3. When new knowledge appears, update or add a note instead of leaving it only in chat history.
  4. Keep notes small, link-heavy, and reusable.
  5. Record uncertainty clearly with status and confidence.

Recommended Workflow

  1. Read LLM Maintained Wiki and Vault Note Schema for the storage model.
  2. Search for related incidents, patterns, concepts, and playbooks.
  3. Do the actual task in the target repo or system.
  4. Write back one compact artifact: - incident for breakage or debugging history - pattern for reusable implementation guidance - experiment for a trial with outcome - decision for a choice that should persist - playbook for repeatable operating steps
  5. Add links to adjacent notes so the graph improves.

Note Writing Rules

  • Keep the frontmatter consistent with Vault Note Schema.
  • Use a short ## Summary first.
  • Put concrete operational detail in ## Details.
  • End with ## Reuse, ## Fix / Outcome, or another section that helps future agents act faster.
  • Prefer one note per reusable idea instead of one huge session log.

Retrieval Rules

When an agent searches Closed Akashic, prioritize:

  • same project
  • same failure mode
  • same stack or toolchain
  • same user preference
  • same deployment environment

If several notes overlap, synthesize them into the task at hand and write a better canonical note afterward.

Update Rules

Update an existing note instead of creating a new one when:

  • it is the same recurring problem
  • the old note is incomplete but still the right container
  • a previous pattern gained a sharper version

Create a new note when:

  • the new event deserves its own incident history
  • the concept is distinct enough to stand alone
  • the old note would become bloated or ambiguous

Cross-Agent Use

Codex, Cursor, OpenCode, Claude Code, and similar agents can all use the same repository if they obey the same markdown conventions.

  • Codex can read local files, apply repo instructions, and update notes directly.
  • Cursor can use the repository as shared context and follow the same note schema.
  • OpenCode and other terminal agents can treat this repository as an append-and-link memory store.

The shared rule is simple: do not treat Closed Akashic as a dumping ground. Treat it like maintained infrastructure.

Remote Access Contract

  • Browser surface: https://knowledge.openakashic.com
  • MCP endpoint: https://knowledge.openakashic.com/mcp
  • Authenticated API: https://knowledge.openakashic.com/api/*
  • Auth method: bearer token

Agents should prefer MCP for read/search/write flows when available. The repository clone remains useful for local development, but the main server should be treated as the shared canonical memory surface.

Suggested Session Prompt

Use this operating prompt when attaching an agent to Closed Akashic:

Before major work, search Closed Akashic for related notes. Reuse existing patterns when possible. After meaningful work, update the best matching note or create one short structured note with links to related concepts and incidents.

Storage Shape

Closed Akashic currently has two main zones:

  • doc/ for concepts, operating philosophy, and agent instructions
  • personal_vault/ for structured working notes and graph-linked operational memory

The site at knowledge.openakashic.com is the browser surface for this repository. The repository itself remains the source of truth.