Memoria

30-second Tour

🤖 AI Agent Quick Install

Install from npm (Recommended)

# One-shot via npx (no install needed)
npx @raybird.chen/memoria setup --serve --json
# Or install globally
npm install -g @raybird.chen/memoria
memoria setup --serve --json

<memoria-home>/.agents/skills/memoria/SKILL.md
<memoria-home>/.agents/skills/memoria/REFERENCE.md

{"step":"preflight","ok":true,"ms":120,"mode":"installed"}
{"step":"init","ok":true,"ms":85}
{"step":"verify","ok":true,"ms":42}
{"step":"skill","ok":true,"ms":14,"path":"./memoria/.agents/skills/memoria"}
{"step":"serve","ok":true,"port":3917}

curl -sf http://localhost:3917/v1/health

curl -X POST http://localhost:3917/v1/remember \
 -H 'Content-Type: application/json' \
 -d @examples/session.sample.json
curl -X POST http://localhost:3917/v1/recall \
 -H 'Content-Type: application/json' \
 -d '{"query":"SQLite migration","top_k":5}'
curl http://localhost:3917/v1/stats

Capability Map

Memoria vs MCP/libSQL

HTTP API

Common CLI Commands

./cli init # Initialize DB + directories
./cli sync <session.json> # Import a session
./cli sync --dry-run <session.json> # Preview without writing
./cli stats [--json] # Statistics
./cli doctor [--json] # Local health check
./cli verify [--json] # Full verification
./cli index build [--json] # Incremental tree-index rebuild
./cli index build --scope agent:main # Rebuild only the given scope
./cli source add notes/research.md # Import a markdown/text source
./cli source list --json # List raw sources
./cli wiki build --json # Rebuild the compiled wiki
./cli wiki file-query --query "TS CLI migration" --title "TS CLI Migration Brief" --kind synthesis --scope project:Memoria
./cli wiki lint --json # Produce durable wiki governance findings
./cli govern review --json # Check for rule/skill promotion candidates
./cli prune --all --dry-run # Cleanup preview (consolidate 90d + stale 180d)
./cli prune --consolidate-days 90 # Merge old session nodes under the same topic
./cli prune --stale-days 180 # Remove memory never hit by recall
./cli export --type all --format json # Export
./cli serve [--port 3917] # HTTP API server
./cli preflight [--json] # Prerequisite check
./cli setup [--serve] [--json] # One-shot install

Node.js SDK

import { MemoriaClient } from './src/sdk.js'
const client = new MemoriaClient() // defaults to http://localhost:3917
await client.waitUntilReady() // poll /v1/health until ready
const r = await client.remember(sessionData)
const hits = await client.recall({ query: 'migration', top_k: 3, scope: 'project:Memoria' })
const telemetry = await client.recallTelemetry({ window: 'P7D', limit: 50 })
const summary = await client.summarizeSession('session_abc')

Agent Adapter

import { GeminiAdapter } from './src/adapter/index.js'
const adapter = new GeminiAdapter({ client, project: 'my-project' })
// Before prompt: inject historical memory
const context = await adapter.beforePrompt({ userMessage, conversationId })
// After response: persist memory (auto throttle + dedupe + fail-open)
await adapter.afterResponse({ response, conversationId, userMessage })

Claude Code (zero-code integration via hooks)

// ~/.claude/settings.json (or .claude/settings.json per project)
{
 "hooks": {
 "UserPromptSubmit": [
 { "matcher": "", "hooks": [{ "type": "command", "command": "memoria adapter claude-code" }] }
 ],
 "Stop": [
 { "matcher": "", "hooks": [{ "type": "command", "command": "memoria adapter claude-code" }] }
 ]
 }
}

Project Layout

src/
 cli.ts # Commander registration shell (~50 lines)
 cli/ # Per-command modules + shared helpers (shared.ts / runtime.ts / preflight.ts / commands/)
 server.ts # HTTP API server (node:http, zero extra deps)
 sdk.ts # MemoriaClient SDK
 core/ # All business logic (types / paths / utils / db/ / memoria / source-import / wiki-*)
 core/db/ # SQLite ops by domain (schema / session / source / wiki / lint / sync / telemetry / verify / prune-export / recall / mappers)
 adapter/ # BaseAdapter + Claude Code / Gemini / OpenCode adapters
scripts/ # End-to-end bash tests (test-*.sh) + release packaging
skills/ # memoria-memory-sync agent skill
examples/ # session.sample.json

Documentation Map

License