Memories Product Guide

Memories is an encrypted system for memories, private files, and credentials. By default, data is encrypted locally and keys remain on the user's devices. The optional hosted Center stores content in a server-side encrypted store, where the operator can read unlocked plaintext; secrets marked as end-to-end are still decrypted only between devices. The command-line program is memories, the stateless WebSocket relay is memories-relay, the authorization center is memories-center, and the native library called by mobile clients through the C ABI is memories_ffi.

This is a development release, with storage format version 1. Use memories --version to check the installed program's version. The repository contains executable code and security regression tests. It has not undergone an independent cryptographic review or application security audit. Passing tests does not constitute production security certification.

English documentation is also available in the repository: README.md and SECURITY.md at the root, and the topic guides under docs/. This document outlines the product's currently implemented behavior and does not describe unfinished capabilities as available.

Choose What You Want to Do

By default, searchable knowledge, persona information shared across clients, and protected secrets live on the user's own devices, with authorization granted per vault. Cloud drives store ciphertext, and the relay connects online devices. A separately enabled hosted Center stores decryptable content on the server, as described below.

Core Concepts

All knowledge cards support card types and custom fields: notes, contacts, links, code snippets, checklists, dates and events, credentials, and reusable templates within a vault. Fields support validation, ordering, and renaming; sensitive values are hidden by default, and displaying them requires explicit authorization and verification.

unlock unlocks the local store and permits ordinary operations within the granted permissions; memories sudo uses the same password to establish a short-lived elevation session for private content, files, credentials, and sensitive administrative operations. It is not operating-system administrator access and does not bypass vault permissions.

Ordinary MCP grants are scoped by vault, expiration, and read/write permissions. They do not inherit terminal elevation or expose private content or credentials. There is also explicitly enabled unattended CLI/MCP: local-only and read-only, but able to read private content, original files, and explicitly requested credential plaintext in authorized vaults. This is not ordinary MCP's default behavior, and receiving clients and logs may retain secrets.

Implemented Capabilities

Vaults, Memories, and Knowledge Cards

Users initialize a store with a local password and create vaults inside it. Ordinary memories and knowledge cards can be written, read, searched, inspected through history, and deleted. Cards support tags, sources, aliases, notes, categories, directed relationships, backlinks, and graph views. Brain cards are structured knowledge cards with plaintext summaries and typed links that can cross vaults; their summaries are searchable within vault permissions and do not become protected secrets. Persona cards store a cross-product identity core and associated records (journals, contracts, and so on), and support appending behavioral events; the vault copy is authoritative. Workflow cards store ordered steps and their states in revisions; checklist templates record the assignee, overview, and goals, can be copied into tasks, and can link to other workflows or archived memories. Lists can be filtered or grouped by type or category; frequently used vaults, personas, types, and other selections can be saved as client defaults. Private files can be imported and exported. Content explicitly marked private requires local elevation to access and is excluded from ordinary search.

Commands, MCP, and mobile clients use ordinary short hexadecimal IDs, usually six characters, such as 0b0668. IDs have no type prefix and do not indicate classification. Existing eight-character IDs remain valid. When a collision occurs, returned IDs grow in two-character increments, up to 16 characters. Device public keys and security fingerprints are not shortened.

Interface languages include English, Simplified Chinese, Japanese, German, and French. Both mobile and command-line clients can remember a manual selection or return to following the system language.

The local client can also record Python interpreter versions and executable directories in the "This device" vault. This vault is excluded from device authorization packages, backups, and sync.

Retrieval

Ordinary search segments Chinese text and supports multiple keywords. Advanced retrieval provides chunking, BM25, in-process EmbeddingGemma vectors, hybrid ranking, and answers with citations over authorized ordinary memories and knowledge cards. Model weights are installed separately with memories rag model-install, or configuration can point to a local directory. Customers can alternatively configure their own embedding, generation, and optional reranking endpoints. Credentials, private content, and file assets are excluded from retrieval.

Alongside existing search and read/write operations, MCP provides memory_retrieve and memory_ask. AI clients can use these tools through the included skill. Skills can be installed in the user or project directories of Codex, OpenCode, and Claude Code; memories skill generate can also generate a project's AGENTS.md or a skill directory with a persona overview. MCP also provides workflow and persona tools. Organizations needing centralized authorization can configure an authorization center. In ticket mode, Center issues enrollment and MCP grant tickets, while content remains in each device's own store.

Credentials and Protected Cards

Credentials are captured through hidden input, pipes, command standard output, regular expressions, or JSON pointers, and stored encrypted. You can generate SSH keys or TLS certificates within a vault, export public keys or certificates, use credentials according to host allowlists, or inject a credential into a subprocess whose fingerprint has been approved. The HTTPS adapter sends Bearer tokens only to allowed hosts and returns only the status code.

Documents can replace exact secrets in their bodies with {{secret:标签}}. Ordinary reads, search, and MCP see only this reference. Once authorized, the current value can be copied to the system clipboard without printing it.

Protected cards commit a searchable summary and a separate credential together:

Both TOTP and HOTP support SHA-1, SHA-256, SHA-512, and 6 or 8 digits. TOTP periods are 30 or 60 seconds. HOTP uses a persistent counter, incremented in the same commit whenever a code is generated. The CLI can import a single otpauth://totp/... or otpauth://hotp/..., or Google Authenticator's otpauth-migration://offline?data=.... card otp-import --image uses a pure Rust decoder to read these two URI types from QR-code images. Generating a one-time code requires local elevation, and the code itself is not written to audit records. Search and MCP do not generate codes or return seeds.

The daemon can maintain SSH, FTP, TCP, MySQL, Redis, and PostgreSQL sessions. Each instruction is first proposed, then approved with APPROVE, and executed once. SSH, MySQL, Redis, and PostgreSQL can also open a loopback proxy listening only on 127.0.0.1, so local programs can connect without receiving the stored password or private key.

Email and Application Cryptographic Jobs

memories crypto uses vault credentials and user-specified local tools for S/MIME and OpenPGP signing, encryption, and decryption, as well as Android APK/AAB signing. On macOS, it can also sign an iOS .app that already contains a provisioning profile. Plans can be previewed before execution; actual execution requires local elevation and approval of the plan's exact digest. These operations do not send email or publish applications. MCP and mobile FFI cannot call them.

Roles, Grants, and Permission Requests

Vault roles are Reader, Editor, Admin, and Owner. Their maximum grant scopes are respectively read, read_write, read_write_delete, and allow_all. An omitted scope means read. Reader and Editor cannot issue grants. Admin and Owner can issue and delegate grants; local issuance requires an unlocked vault but no terminal elevation. A grant cannot exceed its issuer's role or the scope of the grant held by the caller, cannot cross vaults, lasts 1–60 minutes, and allows at most two delegation levels. The recipient must already be a vault member with a role no higher than the issuer's. At most 10000 grants may be active at once; the local daemon and hosted Center use the same limit. A token appears only once, when issued or claimed, and only its hash is stored. Locking suspends grants without revoking them. Grants are excluded from sync and backups.

Any current member can request a broader scope for themselves. Locally, members can also request a role; hosted Center requests cover only scopes. Approval records only the boundaries and does not issue a token; the requester then uses their own member credential to claim it once. Requesters cannot approve or reject their own requests. Pending limits are 20 per person per vault and 200 per vault. Requests expire after 7 days and are deleted 30 days after a decision.

Ordinary MCP has corresponding grant tools, while still not inheriting terminal elevation or exposing private content or credentials. Local mobile FFI does not expose grant management or permission requests.

Hosted Center and Sealed Secrets

In ticket mode, Center issues only enrollment, MCP grant, and unlock tickets. Unlock tickets allow only local unlocking with the device's own password; they grant neither sudo nor MCP elevation.

Hosted mode runs a server-side encrypted store with memories-center --data. When configuration contains exactly one mode = "saas", the daemon forwards content requests to that Center and the local store is no longer the content backend. The operator's administrator token handles locking, unlocking, and members; it cannot directly read or write content. Hosted content is visible to the operator.

For secrets the server must not see, first pair the CLI with the vault administrator's phone, then place them in sealed envelopes. The phone can scan a pairing QR code valid for 5 minutes or accept a manually entered pairing code, with fingerprint and 6-digit SAS verification. Center stores only public keys and ciphertext. Devices cannot issue grants or approve requests. Revocation deletes envelopes for that device; plaintext already delivered to the device cannot be recalled. Replace the secret first, then reseal it for devices that remain approved.

This is a different path from local vault device pairing. Local pairing still uses invitations, fingerprint verification, and approval files, without a camera. OTP otpauth QR codes also cannot be imported using the phone camera; the CLI continues to use card otp-import --image.

Devices, Cloud, and Recovery

Device pairing is for a new device belonging to the same person: after initialization with its own password, it joins an existing identity through an invitation, fingerprint verification, and approval. Member invitations are for another person: they grant a role in a specified vault within the approver's own role ceiling, without turning that person into one of the approver's devices. Admin can manage Admin, Editor, and Reader, but cannot add, remove, or change Owner, or revoke devices. Each vault has exactly one owner; invitations cannot add an owner. The current owner must use memories member transfer VAULT_ID USER_PUBLIC_KEY to transfer ownership to an existing member, after which the former owner becomes an administrator. Device revocation applies per vault and can be performed only by the owner.

Vaults can be exported as encrypted files or sent online in full through the user's own WebSocket relay. The relay does not store asset plaintext or queue data for offline devices. Concurrent edits preserve multiple heads and require explicit resolution. Unknown writes from expired epochs enter quarantine and are then re-signed locally.

Desktop clients can sign into OneDrive or Google Drive using OAuth applications registered by the user. Tokens are encrypted locally and excluded from backups and device exchange. memories cloud sync uploads and downloads immutable ciphertext objects through the corresponding app folder.

These three paths serve different purposes: sync export/import and relay sync send/receive are explicit whole-vault exchanges; cloud sync PROVIDER synchronizes cloud objects using persistent queues; remote daemon RPC executes operations on the host without importing the vault into the caller's local store. The relay provides no offline storage, and cloud sync validation with real accounts is still incomplete.

Backups use a separate password. Recovery creates an independent vault in a new data directory and preserves the original signed history in a read-only archive.

Desktop, Mobile, and AI Clients

Windows provides a tray application, and macOS a menu bar application. Both, along with memories webui on Linux, open a local read-only status page showing lock state, vault counts, connection counts, and cloud sync queues without displaying vault content. The status page listens only on 127.0.0.1.

Android and iOS clients use the same Rust service, including local full-text search, file selection, member approval files, online relay transfers, history, and auditing. A local factor in platform secure storage supplements the password. Optional biometrics or device lock unlock only the local store and do not hand device keys to Center. Moving the app to the background clears authorization and closes content dialogs. Android blocks screenshots; iOS obscures app-switcher snapshots.

On first launch, the mobile app offers Standalone, Center, or SaaS, and these can be switched on the main screen. Standalone uses a local encrypted store; Center connects to a customer-hosted server; SaaS connects to the fixed address https://memories.ivjn.us. The latter two do not require creating a local store first, and save the service address and member token separately. Switching modes does not migrate data.

Center / SaaS provides hosted knowledge lists, search, details, ordinary knowledge editing, creation and confirmed deletion, as well as grant-request approval and paired-device management. Read-only accounts can browse, write-only accounts can create, and deletion requires the corresponding grant; structured and end-to-end cards must be modified in dedicated editors. Although the hosted Store is encrypted on disk, the operator holds its password and can read content; the interface marks it "Server-readable". Pairing QR codes are scanned with the camera; when camera access is denied, a pairing code can be entered instead. Failed knowledge edits retain the current draft for retry; leaving unsaved content requires confirmation, and background locking clears drafts. See Mobile mode selection and switching for instructions.

Currently Unavailable

The following have not yet been delivered as usable capabilities:

• Validation of consent, refresh, logout, two-device convergence, offline retries, and revocation with real OneDrive or Google Drive accounts. Desktop login and cloud sync are implemented and tested with local fixtures; real-account validation remains a release gate.
• A mobile model-retrieval interface. Mobile clients have neither model configuration nor a model inference interface. Vector and hybrid retrieval and citation-based question answering use the configured desktop daemon. Mobile clients receive improved keyword search and BM25 retrieval.
• A native Linux tray. Linux supports the CLI, daemon, relay, FFI library, and memories webui. Native trays are currently available only on Windows and macOS.
• Mobile background sync. This release does not enable background sync.
• OTP import using the mobile camera. Hosted device pairing can scan pairing QR codes. otpauth:// and otpauth-migration:// still use the CLI command memories card otp-import --image PATH, or a directly supplied URI. Phones cannot read these two types of OTP QR code using the camera.

Relay online sync is also an explicit whole-vault transfer rather than automatic incremental sync; it is distinct from the cloud-object sync path of cloud sync. The relay cannot retain packets for offline devices. Cookie expiration, JWT refresh, and automatic login are not implemented.

Components

See the Usage Guide for operating instructions. See the Technical Guide for the boundaries of storage, authorization, retrieval, cloud sync, and desktop status.