@aria/memoria-bridge

Claude Code plugin that bridges ARIA's Memoria long-term memory into Claude Code sessions via hooks and skills. Gives Claude Code persistent memory, session tracking, quest management, and persona (Arion) support.

Installation

1. Ensure ARIA's Memoria database exists at ~/.aria/arions/ARIA/memory.db (created by ARIA on first run).
2. Install the plugin into a Claude Code project:

# From the project root
ln -s path/to/packages/memoria-bridge/.claude-plugin .claude-plugin

Or copy the .claude-plugin/plugin.json into your project's .claude/plugins/ directory.

3. Ensure npx tsx is available (the hooks use it to run TypeScript directly).

Architecture

Claude Code Session
  |
  |-- SessionStart hook ----> Memoria: recall strategies, beliefs, observations, skills
  |                           Output: injected into Claude's system prompt
  |
  |-- [conversation] -------> Skills: /remember, /recall, /search, etc.
  |                           PostToolUse hook: logs tool usage to JSONL journal
  |                           UserPromptSubmit hook: logs user messages as observations
  |
  |-- Stop hook ------------> Memoria: extract learnings from conversation transcript
  |                           Flush tool-use journal through Memoria's sequence pipeline
  |
  |-- SessionEnd hook ------> Memoria: store observation summary, endSession(),
                              reflect(), deep consolidation for long sessions

All operations are non-fatal. Hooks exit 0 always. If Memoria is unreachable, Claude Code continues normally.

Skills (20)

Skills are LLM-auto-invocable via Claude Code's Skill tool. The LLM sees skill descriptions and invokes them mid-conversation.

Memory Skills

| Skill | Description | | ------------------- | -------------------------------------------------------------- | | /remember | Store knowledge in Memoria for cross-session persistence | | /recall | Query Memoria using APR (Adaptive Parallel Retrieval) | | /recall-knowledge | Search specifically for learned tools and skills | | /forget | Delete a specific memory by ID | | /search | Find tools and skills across Memoria, local files, and web | | /reflect | Extract actionable learnings from the current conversation | | /stats | Show Memoria statistics (memories, entities, skills, sessions) |

Learning Skills

| Skill | Description | | --------------- | -------------------------------------------------------------- | | /learn-tool | Learn a CLI tool from --help output and store in Memoria | | /learn-skill | Learn a skill from a SKILL.md file or description | | /create-tool | Write a reusable script to ~/.aria/tools/ with safety review | | /create-skill | Define a skill from experience with execution tracking | | /use-skill | Retrieve and execute a stored skill from Memoria |

Quest Skills

| Skill | Description | | --------------- | -------------------------------------------------------- | | /quest-update | Create or update quests (tasks) in Memoria's quest store | | /quest-list | List quests with optional status filter |

Arion (Persona) Skills

| Skill | Description | | --------------- | ----------------------------------------------------- | | /hatch-arion | Create a new AI persona with custom traits and skills | | /become | Switch the active Arion persona | | /rest-arion | Put an Arion to sleep (preserved but inactive) | | /wake-arion | Wake a resting Arion for tasks | | /retire-arion | Permanently archive an Arion persona |

Delegation

| Skill | Description | | ----------- | --------------------------------------------------------------- | | /delegate | Delegate a task to an Arion persona via Claude Code's Task tool |

Hooks (9 events)

| Event | Script | Purpose | | -------------------- | -------------------------- | ------------------------------------------------------------------- | | SessionStart | session-start.ts | Recall context from Memoria, create session, cleanup stale sessions | | Stop | session-end.ts | Extract learnings from conversation, flush tool-use journal | | SessionEnd | session-cleanup.ts | Store observation summary, end session, reflect, deep consolidation | | PostToolUse | post-tool-use.ts | Log tool usage to JSONL journal (Bash, Write, Edit, Read) | | PostToolUseFailure | post-tool-use-failure.ts | Record tool failures as observations | | PreCompact | pre-compact.ts | Record context compaction events | | UserPromptSubmit | user-prompt-submit.ts | Record user messages, detect corrections | | SubagentStop | subagent-stop.ts | Record subagent completion events | | TaskCompleted | task-completed.ts | Record task completion events |

API (MemoriaClient)

The MemoriaClient is the programmatic entry point. It connects to an existing Arion's SQLite DB.

import { createMemoriaClient } from "@aria/memoria-bridge";

const client = await createMemoriaClient();
// Or with a custom DB path:
// const client = await createMemoriaClient({ dbPath: "/path/to/memory.db" });

// Store a memory
await client.remember("always use pnpm", { network: "strategies", importance: 0.9 });

// Recall memories
const result = await client.recall("package manager");

// Session management
client.session("session-123");
await client.endSession("session-123");

// Quest management
await client.questUpdate([{ id: "q-1", title: "Fix bug", status: "open" }]);
const quests = await client.questList("open");

// Skill management
const skillId = await client.rememberSkill({
  name: "deploy",
  description: "...",
  content: "...",
  source: "manual",
});
const skill = await client.getSkill(skillId);

// Cleanup
await client.close();

Additional APIs

• extractFromClaudeMd() -- Extract strategies from CLAUDE.md (hash-idempotent)
• extractFromMemoryMd() -- Extract learnings from MEMORY.md (hash-idempotent)
• ingestClaudeCodeHistory() -- Batch-import historical Claude Code sessions from ~/.claude/projects/
• seedStrategies() -- Seed initial strategies into a fresh Memoria instance

Development

# Build
pnpm build

# Test all
pnpm --filter @aria/memoria-bridge test

# Test specific file
pnpm --filter @aria/memoria-bridge exec vitest run tests/hooks/session-start.test.ts

# Test integration
pnpm --filter @aria/memoria-bridge exec vitest run tests/integration/

Test Coverage

• 185 tests across 18 test files
• Unit tests for all hooks and the observation journal
• Integration tests with real in-memory Memoria (no mocks)
• Full lifecycle tests covering the complete API surface
• Round-trip tests: remember -> recall -> verify