version: "1.0.0" name: allura-memory-skill description: "Govern persistent Allura Brain memory operations." allowed-tools:

• MCP_DOCKER_search_memories
• MCP_DOCKER_create_entities
• MCP_DOCKER_create_relations
• MCP_DOCKER_add_observations
• MCP_DOCKER_find_memories_by_name
• MCP_DOCKER_delete_entities
• MCP_DOCKER_delete_observations
• MCP_DOCKER_delete_relations
• MCP_DOCKER_execute_sql
• MCP_DOCKER_execute_unsafe_sql
• MCP_DOCKER_list_tables
• MCP_DOCKER_describe_table
• MCP_DOCKER_insert_data
• MCP_DOCKER_query_database
• allura-brain_memory_search
• allura-brain_memory_add
• allura-brain_memory_promote
• allura-brain_memory_get
• allura-brain_memory_list
• allura-brain_memory_delete
• allura-brain_memory_update
• allura-brain_memory_restore
• allura-brain_memory_export
• allura-brain_memory_list_deleted
• mcp__allura-brain__memory_search
• mcp__allura-brain__memory_add
• mcp__allura-brain__memory_promote
• mcp__allura-brain__memory_get
• mcp__allura-brain__memory_list
• mcp__allura-brain__memory_delete
• mcp__allura-brain__memory_update
• mcp__allura-brain__memory_restore
• mcp__allura-brain__memory_export
• mcp__allura-brain__memory_list_deleted
• mcp__MCP_DOCKER__execute_sql
• mcp__MCP_DOCKER__insert_data
• mcp__MCP_DOCKER__search_memories

Allura Memory Skill — Governance Layer

Principle: A brain with manners, not a brain with a knife.

This skill governs how agents interact with Allura Brain safely. It does not replace the memory server or the runtime skill (mcp-docker-memory). It sits between the agent's intent and the memory system, enforcing discipline.

Two-Layer Architecture

┌───────────────────────────────────────────────────────────┐
│  SKILL LAYER (this file)                                   │
│  Agent behavior contract — when, how, why to use memory   │
│  .claude/skills/allura-memory-skill/                       │
├───────────────────────────────────────────────────────────┤
│  RUNTIME LAYER (MCP Docker)                                │
│  Server packaging — Docker container, env vars, transport  │
│  database-server → PostgreSQL :5432 (episodic)             │
│  RuVector semantic graph → via governed Brain API          │
└───────────────────────────────────────────────────────────┘

Dockerfile = runtime packaging. Skill = agent behavior contract.

Primary Tool Pathway

When Allura Brain memory tools are available and healthy, use them (they include deduplication, scoring, and promotion logic). Names vary by harness: Claude Code may expose mcp__allura-brain__memory_search; OpenCode/native aliases may expose allura-brain_memory_search. When they are degraded or unavailable, fall back to MCP_DOCKER_* / mcp__MCP_DOCKER__* tools which connect to the same databases directly.

Companion skills:

• memory-client — when to use memory (the Search→Work→Log loop, five modes)
• mcp-docker-memory — which tools to call (canonical MCP Docker tool names and query patterns)
• This skill — how to use memory safely (governance, promotion, conflict resolution, dual-pathway)

When to use

Use this skill when:

• A user asks the agent to remember something important across sessions
• A workflow needs semantic search over prior events, outcomes, insights, or entities
• The agent must store new memories after a task completes
• The agent needs to retrieve relevant project or user context before acting
• The agent must distinguish raw traces from curated knowledge
• The agent needs to promote, supersede, deprecate, or revoke a memory
• The agent is unsure whether to write, update, or supersede a fact
• The agent found conflicting memories and needs resolution logic
• A memory system built on Allura Brain — PostgreSQL (episodic) + RuVector semantic graph — needs setup or troubleshooting

Memory operating model

Treat memory as three distinct layers:

Layer 1: Raw Trace (PostgreSQL)

• What: Session events, observations, evidence, commands, builds, tests
• Store: Every actionable event via memory_add or MCP_DOCKER_insert_data
• Discipline: Append-only. Never update or delete trace rows.
• Status: Raw. Not truth. Not actionable until promoted.

Layer 2: Curated Insight (RuVector semantic graph)

• What: Promoted decisions, patterns, ADRs, brand truth, entity facts
• Store: Only after passing promotion policy (see references/allura-promotion-policy.md)
• Discipline: Version via SUPERSEDES relationships. Never mutate in place.
• Status: Canonical. This is actionable truth.

Layer 3: Retrieval Context (Hybrid)

• What: The smallest useful context window for the current task
• Source: Both PostgreSQL trace and semantic graph insight, ranked by relevance
• Discipline: Prefer project-local first, add global only when it improves reasoning

┌─────────────────────────────────────────────────┐
│               RETRIEVAL CONTEXT                  │
│  (smallest useful window for current task)       │
├──────────────────┬──────────────────────────────┤
│  PROJECT-LOCAL   │          GLOBAL               │
│  (scoped to      │  (cross-project patterns,     │
│   group_id)       │   conventions, ADRs)          │
├──────────────────┴──────────────────────────────┤
│         CURATED INSIGHT (Semantic Graph)         │
│  Promoted, versioned, evidence-backed             │
├──────────────────────────────────────────────────┤
│             RAW TRACE (PostgreSQL)                │
│  Append-only, event-level, unvalidated            │
└──────────────────────────────────────────────────┘

Instructions

When a user asks for memory-related work, follow this sequence:

1. Identify the intent

2. Retrieve before writing

Always search before storing. This prevents duplicates and reveals whether a candidate memory already exists.

// Check for existing memories on the same topic
memory_search({
  query: "brand architecture decision monorepo",
  group_id: "allura-team-durham",
  limit: 5
})
// Check the semantic graph specifically for promoted insights
MCP_DOCKER_search_memories({ query: "brand architecture" })

Possible outcomes of the search:

3. Classify the memory

Every memory must have a type before storage:

4. Apply write discipline

Raw traces (PostgreSQL)

Raw traces are cheap and safe. Write freely, but write signal, not noise:

// Good: decision with context
memory_add({
  group_id: "allura-team-durham",
  user_id: "aaker",
  content: "Decision: Position ember-fold as Hero brand. Rationale: Target audience responds to empowerment narratives. Validated by competitive analysis showing 7/10 competitors use Creator archetype, leaving Hero space open.",
  metadata: { source: "conversation", agent_id: "aaker" }
})
// Bad: noise without context
memory_add({
  group_id: "allura-team-durham",
  user_id: "aaker",
  content: "Working on strategy pack for ember-fold",
  metadata: { source: "conversation", agent_id: "aaker" }
})

Insights (semantic graph)

Insights are expensive and permanent. Apply strict discipline:

1. Never create an insight without searching for duplicates first
2. Never mutate an existing insight node — create a new version and link with `SUPERSEDES`
3. Never promote without evidence — raw traces must exist to back the insight
4. Prefer supersede relationships over in-place edits

5. Store evidence with memory

Every memory must carry:

Do not write unsupported claims as durable truth. If you are guessing, mark it. If you lack evidence, store it as a raw trace and defer promotion.

6. Use dual-context retrieval

When acting on behalf of a project, load context in this order:

1. Project-local first — search with group_id scoped to the project
2. Global only when needed — add cross-project patterns, conventions, ADRs
3. Smallest useful window — return what's relevant, not a dump

See references/allura-dual-context-retrieval.md for the full retrieval protocol.

7. Handle conflicts safely

When two memories disagree:

1. Preserve lineage — never delete history
2. Mark one as superseded — use SUPERSEDES relationship, not destructive edits
3. Prefer explicit status edges over silent overwrites
4. If uncertain — store both and flag for human review

// Supersede an old insight with a new one
MCP_DOCKER_create_entities({
  entities: [{
    name: "Decision: Use MCP Docker as single runtime (v2)",
    type: "Decision",
    observations: [
      "Supersedes: Decision v1 which assumed multiple runtimes",
      "Evidence: SASL bug proved single-runtime model is safer",
      "Validated: 2026-04-21 architecture audit"
    ]
  }]
})
MCP_DOCKER_create_relations({
  relations: [{
    source: "Decision: Use MCP Docker as single runtime (v2)",
    target: "Decision: Use MCP Docker as single runtime",
    relationType: "SUPERSEDES"
  }]
})

8. Troubleshoot systematically

See references/allura-troubleshooting.md for the full troubleshooting guide.

Quick checklist:

Write permissions matrix

Not every agent can write everywhere. Respect these boundaries:

Key rules:

• Munari and Scout are read-only — they flag issues but never fix directly
• Only Kotler can write to the semantic graph, and only via SUPERSEDES (never in-place edit)
• Any agent can request promotion, but approval requires HITL

Guardrails

These are non-negotiable. Violating them causes data corruption or CHECK constraint failures.

1. Do not confuse raw logs with validated knowledge. PostgreSQL trace ≠ semantic graph insight.
2. Do not mutate canonical insights in place. Create new version nodes with SUPERSEDES.
3. Do not promote memories without evidence or policy support. See references/allura-promotion-policy.md.
4. Do not create duplicate insight nodes when a superseding relationship is more appropriate. Search first.
5. Do not return stale memory without checking timestamps and status. Check for deprecated flags and SUPERSEDES edges.
6. Do not bypass Brain. Never use local files as fallback. If Brain is down, fix Brain, then work.
7. Do not work without `group_id`. Every call requires it. Pattern: ^allura-[a-z0-9-]+$.
8. Do not skip the search-before-write step. Always deduplicate before storing.

Recovery procedures

Soft-delete (within 30-day window)

memory_delete({
  id: "<memory-id>",
  group_id: "allura-team-durham",
  user_id: "kotler"
})

Restore a soft-deleted memory

memory_restore({
  id: "<memory-id>",
  group_id: "allura-team-durham",
  user_id: "kotler"
})

List soft-deleted memories (recovery window)

memory_list_deleted({
  group_id: "allura-team-durham"
})

Deprecate a semantic graph insight (without deleting history)

// Create a deprecation marker, not a delete
MCP_DOCKER_add_observations({
  entityName: "Decision: Use MCP Docker as single runtime",
  observations: ["DEPRECATED: Superseded by v2 on 2026-04-22"]
})

Recommended references

Read these for deep-dive knowledge:

Recommended scripts