Skip to content

Memories

Memory Operations

This guide documents the current behavior implemented in code.

Akashic exposes memory operations through the memory tool with an action field:

  • memory + action: "get_context"
  • memory + action: "store"
  • memory + action: "search"
  • memory + action: "retrieve"
  • memory + action: "update"
  • memory + action: "delete"
  1. memory + action: "get_context" first.
  2. Process request with returned context.
  3. Persist session:
  4. action: "update" if conversation_memory_id exists and same case.
  5. action: "store" for a new case.

action: "get_context"

Returns identity + active conversation + related memories in one call.

Key inputs: - query (optional) - project_name / project_id (optional, scopes case selection) - detected_identity (optional)

Response fields:

  • identity: the active IDENTITY memory (personality, nicknames, user address, emotional state), or null when no identity is configured.
  • conversation_memory_id: the most relevant active conversation/case memory ID for the project (when project_name/project_id is provided) or for the account, or null when none exists. Use this exact ID for memory action update on the same case.
  • related_memories: semantically related memories based on query (optional).
  • get_context_do_dont: hardcoded workflow rules (unchanged).
  • general_do_dont: owner-wide do/dont preferences with no project scope (unchanged).
  • project_do_dont: legacy project-scoped short-form do/dont. Deprecated in favor of project_rules.do / project_rules.dont.
  • project_rules: guaranteed project-scoped unified long-form rules, returned only when project_name or project_id is provided. Fetched by direct filter (not semantic search), so it is always present and cannot be omitted by ranking or pagination. Shape:
"project_rules": {
  "do":   <memory object> | null,
  "dont": <memory object> | null,
  "todo": <memory object> | null
}

Each entry is a single memory with event_type: "project-rule" and metadata.rule_type: "do" | "dont" | "todo". There is at most one memory per project per rule_type (no fragmentation). The todo variant is a structured SDD document with markdown sections ## Constitution, ## Spec, ## Plan, ## Tasks, ## Gaps. When a project has no rule of a given type, that field is null.

Project rules vs. owner-wide do/dont:

  • general_do_dont is owner-wide (no project): free-form owner preferences.
  • project_rules is project-scoped and unified: one long-form memory per project per rule_type (do/dont/todo), surfaced as single objects (or null) in project_rules. Store them via the rules tool (do/dont) and the todo tool (todo) with project_name/project_id.

action: "store"

Stores a new memory.

Key inputs: - content (required) - collection_name (optional) - metadata (optional) - classification (optional) - tags (optional) - related_memory_ids (optional) - project_name, project_id, environment (optional)

Tag rules for useful memories: - Keep tags short and stable: 2 to 5 tags per memory. - Use lowercase kebab-case: team-sharing, identity-bug, oauth2. - Prefer retrieval-oriented tags: domain, subsystem, error/fix, workflow step. - Use one canonical tag per concept; avoid near-duplicates (auth, authentication, auth-flow at once). - Do not use generic tags that do not help search: important, note, misc, test123. - Include at least one technical anchor tag when applicable: retrieve-memory, get-context, project-share. - For incidents/fixes, include both problem and resolution tags: - Example: retrieve-not-found, shared-owner-fallback.

Semantic search with optional pagination and ordering.

Key inputs: - query or query_embedding (one required) - collection_name (optional) - limit (default 7) - offset (default 0) - sort_order: relevance, updated_at_asc, updated_at_desc, created_at_asc, created_at_desc - classification, tags, filter (optional) - include_files (default false) - max_related_memories (default 5) - compact (default false) - date_boost_enabled (default true)

Current behavior: - Searches requester memories. - Also searches shared project owners when applicable. - Returns grouped results with optional related memories and files.

action: "retrieve"

Retrieves one memory by ID with metadata, linked files, and nested related memories.

Key inputs: - id (required) - collection_name (optional)

Current behavior: - If collection_name is omitted, searches across accessible collections. - Includes shared-project owner collections in fallback ID lookup. - Validates project access before decrypting cross-owner memories. - Includes linked files and related memories up to 3 levels.

action: "update"

Updates existing memory by ID.

Key inputs: - id (required, UUID/string) - content (optional) - metadata (optional) - collection_name (optional) - related_memory_ids, environment, project_name, project_id (optional)

action: "delete"

Deletes by ID.

Minimal JSON-RPC examples

{
  "name": "memory",
  "arguments": {
    "action": "get_context",
    "query": "Current request context",
    "project_name": "AkashicMCP"
  }
}

{
  "name": "memory",
  "arguments": {
    "action": "retrieve",
    "id": "0205f73f-ed71-4550-953e-776bf0587170"
  }
}