@hasna/mementos

Persistent memory for AI agents, available as a CLI, MCP server, REST service, and TypeScript library. Mementos stores memories in local SQLite by default and can route clients to a self-hosted PostgreSQL-backed service over an authenticated HTTP API.

Install

Mementos requires Bun 1.0 or newer at runtime.

npm install -g @hasna/mementos
# or
bun add -g @hasna/mementos

The package installs three binaries:

| Binary | Purpose | | --- | --- | | mementos | Memory, agent, project, graph, session, and maintenance CLI | | mementos-mcp | MCP server; Streamable HTTP by default, stdio on request | | mementos-serve | REST API and dashboard server |

Quick start

Local mode needs no service or database configuration. The first command creates and migrates ~/.hasna/mementos/mementos.db.

mementos save project-stack "Bun, TypeScript, SQLite" \
  --scope shared --category fact
mementos recall project-stack
mementos search "TypeScript"
mementos list --scope shared

Register an agent and project when memories need explicit ownership:

mementos projects --add --name my-project --path "$PWD"
mementos register-agent marcus --role coding-agent
mementos inject --project "$PWD" --agent marcus --format compact

Memory scopes are global, shared, private, and working. working is transient session scratch space and defaults to a one-hour lifetime. Categories are preference, fact, knowledge, history, procedural, and resource.

CLI

mementos --help
mementos <command> --help

Human-readable list and search commands are compact and paginated by default. Use --limit with --cursor or --offset, --verbose for wider snippets, and mementos show <id> for a full record. Use global --json or a supported --format json|csv|yaml option for structured output.

mementos list --limit 20 --cursor 20
mementos search "deploy" --verbose
mementos --json list
mementos storage mode --json

The complete command tree and option conventions are in the CLI reference.

MCP

mementos-mcp defaults to a shared, stateless Streamable HTTP server bound to 127.0.0.1:8867:

mementos-mcp
# explicit equivalent
mementos-mcp --http --port 8867

Endpoints are GET /health and POST /mcp. Set MCP_HTTP_PORT to change the port. For an MCP host that launches a child process over stdio, opt in explicitly:

mementos-mcp --stdio
# or: MCP_STDIO=1 mementos-mcp

Cursor, Codex, Claude, and other command-based MCP host entries should use command = "mementos-mcp" with args = ["--stdio"].

The server exposes its live tools plus mementos://memories, mementos://agents, and mementos://projects. MCP tools/list is the complete schema source; the convenience search_tools and describe_tools calls cover the smaller registered utility discovery catalog. See the MCP reference for installation examples and the full tool inventory.

REST API

mementos-serve --port 19428

The server binds to 127.0.0.1 unless MEMENTOS_HOST is set. /v1 is the canonical API prefix and /api is a backward-compatible alias. Operational probes and the generated contract are available without authentication:

GET /health
GET /ready
GET /version
GET /openapi.json

API routes use bearer/API-key authentication when configured. See the REST API reference.

Storage

Local clients

SQLite is authoritative by default. Database selection order is:

1. HASNA_MEMENTOS_DB_PATH or MEMENTOS_DB_PATH.
2. The nearest existing .mementos/mementos.db walking up from the current directory.
3. Git-root .mementos/mementos.db when MEMENTOS_DB_SCOPE=project.
4. ~/.hasna/mementos/mementos.db.

Legacy ~/.mementos data is copied to ~/.hasna/mementos when the new directory does not yet exist.

Server backend and HTTP clients

There are no deployment modes. The only runtime switch is the server data backend: sqlite | postgresql, selected by HASNA_MEMENTOS_DATABASE_URL presence. Raw PostgreSQL credentials are server-only — configure mementos-serve with HASNA_MEMENTOS_DATABASE_URL; configure CLI and MCP clients with the HTTPS API endpoint and API key instead:

# mementos-serve environment
HASNA_MEMENTOS_DATABASE_URL=postgres://...

# client environment; do not distribute the database URL to clients
HASNA_MEMENTOS_API_URL=https://mementos.example.com
HASNA_MEMENTOS_API_KEY=...

Both API variables must be present to select the HTTP client transport, and exactly one of them set is an error naming the missing variable. mementos storage mode reports the chosen transport without opening a database or making a network request. Any retired storage-mode variable (HASNA_MEMENTOS_STORAGE_MODE or an alias) is an error: delete it.

The old storage push, pull, and sync commands remain for compatibility; they are not the cutover architecture. See Configuration and storage and the cloud cutover runbook.

TypeScript APIs

The main package exports the synchronous database/domain API from @hasna/mementos and an authenticated fetch client from @hasna/mementos/sdk. The repository also contains the separately published zero-dependency @hasna/mementos-sdk client. See Library and SDK APIs and the standalone SDK README.

Shared event webhooks

The CLI includes the events and webhooks command groups supplied by @hasna/events, allowing memory events to trigger command or HTTP automation. Inspect their installed-version help before configuring a webhook:

mementos events --help
mementos webhooks --help

Event command handlers receive the envelope on stdin and in HASNA_EVENT_JSON. Include working_dir, project_path, or repo_path when a downstream agent must run in a particular repository.

Development

bun install
bun run typecheck
bun test
bun run build

Development entry points are bun run dev:cli, bun run dev:mcp, and bun run dev:serve.

Documentation

• CLI reference
• MCP reference
• REST API reference
• Configuration and storage
• Library and SDK APIs
• Cloud cutover runbook

License

Apache-2.0 — see LICENSE.