@hasna/mementos weekly downloads statistics

@hasna/mementos

Persistent memory for AI agents, available as a CLI, MCP server, REST service, and TypeScript library. Hosted clients use the authenticated Mementos HTTP API; local SQLite is available only through an explicit local-mode opt-in.

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 server

Quick start

Local mode must be selected explicitly. The first command after the opt-in creates and migrates ~/.hasna/mementos/mementos.db.

export HASNA_MEMENTOS_LOCAL=1
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.

For CLI context and inject, an explicit --project must resolve to a registered project and restricts every included scope to that exact project. SDK getContext({ project_id }) uses the same exact-project rule. Unknown explicit projects fail before memories are selected or touched; omitting the project keeps the existing scope selection.

The library and MCP injection strategies retain unassigned agent-private context alongside the selected project's private memories. They exclude private memories assigned to another project. Their existing global/shared policies remain: library strategies include global memories across projects and project-scoped shared memories; direct MCP injection also scopes global memories to the project, while its full smart pipeline uses the library policy.

Injection project references may be a stable project ID, registered name, or registered path. Library, MCP, and HTTP/SDK injection resolve that reference once and use the stable project ID for every downstream profile, search, filter, hook, and touch path.

The list API and SDK expose include_unassigned_project: true with project_id for this union. The filter applies before pagination and also governs total; without a project it has no effect. Omitting it keeps an exact project match.

CLI

Optional decision assistance

Decision assistance is off by default. No provider account or key is needed for ordinary Mementos commands. Configure and enable the features you want from the CLI; there is no web setup. This adds no service-side configuration and does not change ordinary search, context injection, or consolidation.

mementos decisions status --json
mementos decisions configure --provider openrouter --model typesafe/jev-1.13
mementos decisions enable --retrieval --relationships
# Supply OPENROUTER_API_KEY through your secret manager's process environment.
mementos --project my-project decisions search "release approval policy" --limit 10 --json
mementos decisions evaluate --input pair.json --json
mementos decisions disable

For prompt hooks, mementos prompt-context --enabled --input - accepts JSON containing prompt, project and optional explicit scope filters. It returns a bounded, read-only context receipt. Without --enabled it performs no retrieval; provider decisions still require their separate opt-in. The Hooks app registers the native event with hooks install mementos-context --target codex (also claude or codewith). See the prompt hook setup for environment enablement, project scope, provider disclosure and native trust.

configure always leaves assistance disabled. enable permits only the selected features and explicitly permits sending their text to the configured provider. The key is read from OPENROUTER_API_KEY; it is never saved in decision settings. status reports key presence without verifying or calling the provider. Settings are versioned client preferences in the Mementos data root's decisions.json; updates reject concurrent changes. status, configuration, and evaluate do not open a memory store or require a hosted Mementos account.

decisions search retrieves a bounded candidate set using the existing project, agent, session, scope, category, and tag filters, then optionally reranks it. Every candidate is retained; ties preserve the original order. On a missing key, timeout, invalid answer, oversized input, or provider failure, the original ordering is returned with an explicit assessment reason. This command has no pagination cursor: its receipt names ranking_scope: "returned_candidates" and reports has_more. Use ordinary search for pagination. JSON includes compact snippets and source IDs/versions, with a 128 KiB output ceiling.

evaluate accepts a JSON file or stdin (--input -). A relationship input is:

{
  "task": "relationship",
  "candidates": [
    { "id": "a", "text": "Production deployment requires approval." },
    { "id": "b", "text": "Production deployment does not require approval." }
  ]
}
```…