Getting Started

Welcome to Akashic MCP! This guide provides a quick overview of what Akashic MCP is and how to get started.

What is an MCP?

MCP (Model Context Protocol) is a standard protocol that allows AI assistants (like Claude, GPT-4, or other LLMs) to connect to external services to access tools and data from your favorite IDE or development environment.

Akashic MCP is a persistent memory service that enables AI assistants to:

• Remember information across conversations and sessions
• Search memories using intelligent semantic search
• Organize information into thematic collections
• Maintain context across multiple projects and tasks

Unlike other solutions, Akashic MCP works entirely in the cloud - you don't need to install local servers, databases, or configure anything complicated.

Quick Setup

Setting up Akashic MCP is simple and requires no installation:

1. Get your MCP token: Log in to your Akashic MCP account and navigate to Settings to create or copy your MCP token
2. Configure your client: Follow the Installation Guide for detailed instructions for your specific IDE or LLM client (Cursor, ChatGPT, VSCode, Claude Desktop, etc.)
3. Start using: Once configured, your AI assistant will automatically use Akashic MCP to remember and retrieve information

For detailed installation instructions for your specific client, see the Installation Guide.

What's Next?

Once configured, your AI assistant will be able to:

• Save memories automatically when you complete important tasks
• Search information from previous conversations using semantic search
• Remember your preferences and architectural decisions
• Maintain context across different projects

Everything works automatically - you don't need to do anything else. The assistant will use Akashic MCP when appropriate.

Step 3: Create Your Project Main Memory

After installation, we strongly recommend creating a Project Main Memory for each of your projects. This is a special memory that serves as the central hub for your project's context, architecture, and key decisions.

Why Create a Project Main Memory?

flowchart TD
    Start[Project Setup] --> Create[Create Project Main Memory]
    Create --> Benefits[Benefits]

    Benefits --> B1[Central Context Hub]
    Benefits --> B2[Architecture Reference]
    Benefits --> B3[Key Decisions Tracker]
    Benefits --> B4[Better AI Understanding]

    B1 --> Result[AI Assistant Always<br/>Knows Your Project]
    B2 --> Result
    B3 --> Result
    B4 --> Result

    style Create fill:#4ecdc4,stroke:#2c3e50,stroke-width:2px
    style Result fill:#95e1d3,stroke:#2c3e50,stroke-width:2px
    style Benefits fill:#ffe66d,stroke:#2c3e50,stroke-width:2px

How to Create It

Simply ask your AI assistant:

"Create a project main memory for [your-project-name]"

Your assistant will automatically: - Create a memory with event_type: "project-main" and state: "active" - Include your project's core information - Set it up as the central reference point

Important: Each project can only have one active main memory. If you need to update it, the assistant will update the existing one automatically.

What to Include

Your project main memory should contain:

• Project Overview: What the project does, its purpose
• Architecture: Key technologies, frameworks, patterns
• Key Decisions: Important architectural or design choices
• Current State: What's working, what's in progress
• Important Files: Links to key documentation or diagrams

The assistant will help you create a comprehensive main memory automatically.

Step 4: Understanding Memory Classifications

Akashic MCP uses classifications to organize memories and make them easier to find. Understanding these classifications will help you get the most out of the system.

The Four Classifications

flowchart LR
    subgraph Classifications[Memory Classifications]
        DO[DO<br/>Instructions]
        DONT[DONT<br/>Warnings]
        TODO[TODO<br/>Tasks]
        NOTES[NOTES<br/>Information]
    end

    DO --> DO_USE[What to DO]
    DONT --> DONT_USE[What to AVOID]
    TODO --> TODO_USE[Future Tasks]
    NOTES --> NOTES_USE[General Info]

    style DO fill:#4ecdc4,stroke:#2c3e50,stroke-width:2px
    style DONT fill:#ff6b6b,stroke:#2c3e50,stroke-width:2px
    style TODO fill:#ffe66d,stroke:#2c3e50,stroke-width:2px
    style NOTES fill:#95e1d3,stroke:#2c3e50,stroke-width:2px

1. DO - Instructions and Procedures

Use "do" for things you must do or how to do something.

When to use: - User instructions or preferences - Procedures and workflows - Coding standards and conventions - How to complete specific tasks

Examples:

flowchart TD
    DO[DO Classification] --> E1["User preference:<br/>All new files use TypeScript"]
    DO --> E2["Procedure:<br/>Create API endpoint:<br/>1. Validate input<br/>2. Use async/await<br/>3. Include error handling"]
    DO --> E3["Coding standard:<br/>Always use const/let,<br/>never var"]

    style DO fill:#4ecdc4,stroke:#2c3e50,stroke-width:2px
    style E1 fill:#e8f5e9,stroke:#4caf50,stroke-width:1px
    style E2 fill:#e8f5e9,stroke:#4caf50,stroke-width:1px
    style E3 fill:#e8f5e9,stroke:#4caf50,stroke-width:1px

Real-world example:

"When creating API endpoints: validate input, use async/await, include error handling"

2. DONT - Warnings and Restrictions

Use "dont" for things you must avoid or should not do.

When to use: - Things to avoid - Anti-patterns - Warnings and restrictions - What NOT to do

Examples:

flowchart TD
    DONT[DONT Classification] --> E1["Never use setTimeout<br/>or setInterval"]
    DONT --> E2["Don't commit<br/>secrets to git"]
    DONT --> E3["Avoid using var,<br/>use const/let instead"]

    style DONT fill:#ff6b6b,stroke:#2c3e50,stroke-width:2px
    style E1 fill:#ffebee,stroke:#f44336,stroke-width:1px
    style E2 fill:#ffebee,stroke:#f44336,stroke-width:1px
    style E3 fill:#ffebee,stroke:#f44336,stroke-width:1px

Real-world example:

"Never use setTimeout or setInterval in the codebase"

Tip: DONT memories are often linked to related DO memories to provide complete context.

3. TODO - Future Tasks

Use "todo" for future tasks or things you need to do later.

When to use: - Pending tasks - Future improvements - Things to implement later - Backlog items

Examples:

flowchart TD
    TODO[TODO Classification] --> E1["Refactor authentication<br/>module"]
    TODO --> E2["Add error handling<br/>to user service"]
    TODO --> E3["Update documentation<br/>for API v2"]

    style TODO fill:#ffe66d,stroke:#2c3e50,stroke-width:2px
    style E1 fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
    style E2 fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
    style E3 fill:#fff9c4,stroke:#fbc02d,stroke-width:1px

Real-world example:

"Need to refactor the authentication module to support OAuth2"

4. NOTES - General Information

Use "notes" for general information, facts, or context (this is the default).

When to use: - General information - Facts and context - Observations - Project details - When no other classification fits

Examples:

flowchart TD
    NOTES[NOTES Classification] --> E1["Project uses<br/>PostgreSQL database"]
    NOTES --> E2["API endpoint:<br/>/api/users"]
    NOTES --> E3["User name is John,<br/>prefers dark theme"]

    style NOTES fill:#95e1d3,stroke:#2c3e50,stroke-width:2px
    style E1 fill:#e0f2f1,stroke:#26a69a,stroke-width:1px
    style E2 fill:#e0f2f1,stroke:#26a69a,stroke-width:1px
    style E3 fill:#e0f2f1,stroke:#26a69a,stroke-width:1px

Real-world example:

"The project uses PostgreSQL 16 and Express 5.x framework"

Quick Reference Guide

graph TD
    Q{What type of<br/>information?} --> I1[User instruction<br/>or procedure?]
    Q --> I2[Something to<br/>avoid?]
    Q --> I3[Future task<br/>or pending?]
    Q --> I4[General info<br/>or fact?]

    I1 -->|Yes| DO[Use DO]
    I2 -->|Yes| DONT[Use DONT]
    I3 -->|Yes| TODO[Use TODO]
    I4 -->|Yes| NOTES[Use NOTES]

    style DO fill:#4ecdc4,stroke:#2c3e50,stroke-width:2px
    style DONT fill:#ff6b6b,stroke:#2c3e50,stroke-width:2px
    style TODO fill:#ffe66d,stroke:#2c3e50,stroke-width:2px
    style NOTES fill:#95e1d3,stroke:#2c3e50,stroke-width:2px

How Your Assistant Uses Classifications

Your AI assistant automatically:

1. Classifies memories when storing them based on content
2. Searches by classification to find relevant information quickly
3. Links related memories (e.g., DO and DONT memories together)
4. Retrieves context based on what you're working on

Example workflow:

sequenceDiagram
    participant You
    participant AI as AI Assistant
    participant MCP as Akashic MCP

    You->>AI: "Create API endpoint"
    AI->>MCP: search_memory(classification: "do", tags: ["api", "endpoint"])
    MCP-->>AI: Returns: "Validate input, use async/await..."
    AI->>MCP: search_memory(classification: "dont", tags: ["api"])
    MCP-->>AI: Returns: "Never use setTimeout..."
    AI->>You: Creates endpoint following your rules
    AI->>MCP: store_memory(classification: "notes", content: "Created /api/users endpoint")

Best Practices

1. Be specific: The more specific your memories, the better the AI can use them
2. Use tags: Always add 3-5 relevant tags for better searchability
3. Link related: DO and DONT memories are often linked together
4. Update regularly: Keep your project main memory up to date
5. Let the AI help: Your assistant will automatically classify memories correctly

Project Rules: Unified Long-Form (do/dont/todo)

For project-scoped instructions and the SDD workflow document, Akashic MCP provides a unified project rules memory type (event_type: "project-rule"). Unlike the four free-form classifications above, project rules follow a strict one memory per project per rule_type model with long-form markdown content:

• do — the project's operative instructions (one memory).
• dont — the project's warnings and anti-patterns (one memory).
• todo — the project's Spec-Driven Development document (one memory), with markdown sections ## Constitution, ## Spec, ## Plan, ## Tasks, ## Gaps. This replaces spec-kit filesystem artifacts (spec.md, plan.md, tasks.md, constitution.md) as the canonical SDD store.

Storing project rules (upsert, never fragment):

• Project do/dont: the rules tool with project_name (or project_id) and rule_type: "do" | "dont". Storing when one already exists updates the single existing memory instead of creating a duplicate.
• Project todo (SDD document): the todo tool with project_name. The todo tool also exposes update_section (section: constitution | spec | plan | tasks | gaps) to evolve one section at a time, and a project-scoped complete action that flips - [ ] T00X → - [x] T00X inside ## Tasks.

Always-on retrieval via get_context:

Whenever memory action get_context is called with project_name or project_id, the response always includes a top-level project_rules field:

"project_rules": { "do": <memory>|null, "dont": <memory>|null, "todo": <memory>|null }

These are fetched by direct filter (not semantic search), so they cannot be omitted by ranking or pagination — your assistant will always read and follow them when working on your project.

Relationship to other do/dont sources:

• general_do_dont (owner-wide preferences, no project): unchanged.
• project_do_dont (legacy project-scoped short-form): deprecated in favor of project_rules.do / project_rules.dont.
• get_context_do_dont (hardcoded workflow rules): unchanged.

Need Help?

• Discord Community: Join our Discord server to get support, share feedback, ask questions, and connect with other users
• Installation: See the Installation Guide for client-specific setup instructions
• API Reference: Check the API Reference to see all available capabilities
• Authentication: Consult the Authentication Guide if you have access issues
• Advanced Usage: Explore the Memory Management Guide for advanced use cases

---

Note: Akashic MCP is a cloud service. You don't need to install Node.js, Docker, databases, or any other software. Everything works over HTTP from anywhere.