@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.

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.

Register an agent and project when memories need explicit ownership:

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.

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:

For relevance, use "task": "relevance", a non-empty "query", and a "candidates" array of the same {id,text} shape. Relationship suggestions are equivalent, complementary, contradictory, unrelated, or uncertain. Evaluation is read-only: suggestions never authorize writes or replace source authority, human review, or version checks. An unavailable evaluation exits 2; a disabled evaluation exits 0 with an explicit disabled receipt.

The built-in adapter calls OpenRouter's Decisions API with a pinned model ID, no automatic retries, and provider fallback disabled. Defaults bound each assessment to 20 candidates, 16,000 serialized input characters, and five seconds; configure these with --max-candidates, --max-input-chars, and --timeout-ms. Input files are limited to 256 KiB and provider responses to 64 KiB. Only query and candidate text go to OpenRouter; arbitrary metadata and candidate IDs are excluded. Known secret patterns and credential-bearing URLs are redacted before transmission. Redaction is heuristic: enable this only for content you are permitted to send to your chosen provider.

Jev returns judgments, not generated memories or embeddings. Its confidence is distribution concentration, not a probability of correctness. Pinning the model and criteria makes requests reproducible but does not promise deterministic provider answers. Keep structural validation and authorization deterministic.

Other providers, including local implementations, can implement the public DecisionProvider interface; no OpenRouter dependency is required by callers:…

Description from the npm listing.