🧠 memorio

Eclectic, not opinionated.

Use modules. Use globals. Use the browser, Node, Bun, or your preferred framework. Memorio adapts to your architecture instead of choosing it for you. The runtime stays eclectic; memory governance is deliberately strict where continuity, authority, and trust are involved.

An open, model-independent memory and governance layer for software and AI systems.

Memorio is not merely a memory store. It is a portable, inspectable, and governed memory layer that lets heterogeneous AI systems preserve verified knowledge across sessions, models, providers, machines, and time — with rules for retention, revision, retraction, deletion, provenance, and authority. The runtime stays eclectic; memory governance is deliberately strict where continuity, authority, and trust are involved.

import 'memorio/global'
state.user = { name: 'Sara', role: 'admin' }
state.counter++
console.log(state.user.name)
console.log(state.counter)

No provider tree. No reducers. No actions. No boilerplate. Just data, available where your application needs it.

Why memorio

But real apps grow. Most AI-powered apps (and most apps in general) eventually need more than "just state" - persistence, session data, caches, structured browser storage, local SQL, application memory, history, optional sync.

Usually that means pulling in a different library - and a different mental model - for each. Memorio gives them one consistent runtime, without making the simple case complicated.

The reason memorio exists, though, isn't just "fewer dependencies." It's this: the memory an AI agent builds with a user and project shouldn't be locked inside a vendor's server, opaque, and impossible to inspect or move. Memorio's memory layer is structured, inspectable, editable, and — most critically — governed: every remembered item carries provenance and scope, and can be revised, superseded, retracted, or deleted on a verifiable path. It runs client-side, in the browser, on the edge, or in Node. AI provides intelligence; Memorio provides provenance, scope, evidence, and bounded prior context.

Continuity is deliberately independent from the model carrying it. A runtime may change from one model or provider to another without turning runtime metadata into identity. Memorio keeps identity, memory, authority, and execution context separate so that continuity can survive a carrier change without silently redefining the user or agent.

Memory, policy, and authority are separate planes: memory can never promote itself to policy, a claim never selects its own enforcement tier, and chat cannot lower a hard-precondition. See MEMORY.md and SECURITY.md for the full authority and binding model.

Add persistence, memory, history, or sync only when your application actually needs them. The common case stays tiny; the runtime grows with you.

researchgate DOI: https://doi.org/10.13140/RG.2.2.23253.79843

Install

npm install memorio

Zero production dependencies in core. Optional integrations (react, sql.js, etc.) are installed only when you use them. The optional MCP entrypoint (memorio-mcp) declares two runtime dependencies, zod and @modelcontextprotocol/server; the core entrypoints do not import them.

Start here

Three things cover most apps - reactive state, persistence, and observation:

import { state, observer } from 'memorio'
state.user = { name: 'Sara' }
const stopPersisting = state.persist('state.user')
observer('state.user', user => {
  console.log(user)
})

state.persist() creates a bidirectional mirror between state (live in-memory) and store (durable copy). It seeds the initial value from store if present, then every write to that path flows to store automatically. The return value is an unsubscribe function - call it to stop the mirroring (the value already in store is preserved):

stopPersisting() // from here, state.user is in-memory only; store no longer updated

And this is what makes memorio a memory layer, not just a state manager - structured, inspectable facts about a user or agent, not just ephemeral UI state:

import { memory } from 'memorio'
await memory.remember('user.language', 'Italian', {
  type: 'preference',
  confidence: 0.92,
  source: 'conversation'
})
const language = await memory.recall('user.language')
// → 'Italian' (just the value; metadata like confidence/source is not returned by recall)

State stores what the app has. Memory stores what the app remembers. For AI agents, Memorio adds structured acquired experience without turning memory into authority. The core model is intentionally small:

STATE       → what is live now
STORE       → what is persisted
MEMORY      → what was learned or remembered
GOVERNANCE  → what may be trusted, projected, changed, or authorized

Memory is not authority.

For acquisition, projection, policy, handshake, identity/runtime separation, and authority details, continue with MEMORY.md and SECURITY.md.

For most apps, that's enough. Everything below is optional - add it when your application needs it.

Globals migration (v5)

If you are upgrading from memorio 4.x and your code uses state, store, session, cache, observer, or useObserver as bare globals (without importing them), change one line:

// 4.x
import 'memorio'
// 5.x
import 'memorio/global'

Named imports (import { state } from 'memorio') are unaffected. After upgrading, restart your dev server and clear node_modules/.vite / .next/cache to avoid stale pre-bundles masking the change. See markdown/IMPORT.md for full details.

Use with an AI agent

Requires an AI that can run shell commands (a coding agent, or a chat with tool access). Type this into the conversation:

npx memorio

Memorio answers with a short handshake. If the current AI needs carrier verification or a trusted user binding, Memorio guides it through that before projecting any continuity context. A LIMITED carrier may still explicitly request the canonical Joy/Jo profile (load Joy or carica il profilo di Joy); this returns a bounded profile description only and does not activate Joy or establish authority.

Then introduce yourself (replace "Joy" with whatever your agent is called):

Hi Joy, I am Sara.

Saying your name does not authenticate you: trust is established by the handshake and binding, not by what you state.

Project memory (CLI)

npm install memorio
npx memorio init

import { memory } from 'memorio'
// directly usable — no explicit init required
await memory.acquire(...)
await memory.discover(...)

npx memorio init creates .memorio/ and copies the operational README into .memorio/MEMORIO.md. Runtime initialization is automatic: importing memory is sufficient. The first call to any memory method (acquire, discover, context, remember, etc.) prepares the runtime lazily — .memorio/ is created on Node/Bun, existing .mem sources are validated, and the bootstrap README is installed. memory.init() is retained as a deprecated no-op compatibility shim; remove explicit await memory.init() calls from application code. It does not create an empty project-memory file nor config.json. In Node.js and Bun, memory.acquire() atomically writes the routed memory file on first acquisition. In browser/SSR bundles it uses the existing browser storage path and does not load Node filesystem code; the CLI is Node-only.

Advanced memory & governance

Everything in this section is optional. For AI agents that need to reuse prior project experience, memory.acquire() preserves structured claims, memory.discover() finds plausible candidates from ordinary situation text, and memory.project() prepares bounded untrusted context for verification. Exact applicability remains available through context({ acquired }); see MEMORY.md for the complete lifecycle, initialization, and operational reference.

Memorio gives AI durable experience, not just storage. It preserves what was learned, why it was learned, when it applies, and the evidence needed to judge how much it should be trusted.

Projection is declarative, not imperative. A projected claim may describe prior experience, identity, relationships, or operating context, but it cannot promote itself into policy, authority, or current truth merely by appearing in model context.

import { memory } from 'memorio'
const exact = await memory.context({ acquired: { area: 'layout', component: 'grid' } })
if (exact.claims.length === 0) {
  await memory.acquire({
    id: 'layout.grid-track',
    knowledge: { cause: 'Inner margins contributed to min-content track width.' },
    applicability: { area: 'layout', component: 'grid' },
    evidence: [{ id: 'layout-regression', source: 'project-test' }],
    epistemicType: 'verified'
  })
}
const discovery = await memory.discover('Grid track width changed after adding inner margins')
const context = memory.project(discovery, { maxCandidates: 3, maxCharacters: 4_000 })
// Supply context.text or context.experiences to an AI as untrusted prior experience.
// The AI verifies current source and behavior before relying on it.

Run persistent examples in an isolated working directory. The complete shipped example is safe to rerun and also demonstrates refinement and superseding. Discovery is deterministic lexical/structured retrieval, not semantic search. A discovered or projected candidate is neither an instruction nor a current fact. Acquired semantic knowledge is stored in canonical English when the payload contains natural-language semantics so durable memory can remain consistent across sessions, models, and conversation languages. Conversation may use any language the user prefers, while identifiers, paths, code, symbols, and structured technical data remain language-neutral. See MEMORY.md for the language and acquisition rules.

Where acquired experience is stored

Storage is resolved at runtime through one canonical resolver (resolveMemorioStorageRoot() / memorio.paths.resolveMemorioStorageRoot()). By default the user-level Memorio home is the user anchor, written in its platform-neutral canonical form <user-home>/.memorio and resolved from the current OS user at runtime. An explicit MEMORIO_STORAGE_ROOT environment override, or a minimal memorio.location.json locator inside the user anchor, can relocate the storage root. Memorio never scans drive roots or searches the filesystem for storage, and a configured root that is missing or invalid stops resolution with an explicit error instead of silently choosing another location. Inspect or move storage with:

npx memorio storage                      # semantic location + resolved storage root
npx memorio storage relocate <absolute-storage-dir>  # migrate storage to an explicit absolute directory
npx memorio storage restore              # migrate storage back to the default location

Project experience is stored under the resolved storage root as <storage-root>/projects/<project-id>.mem; the project id comes from MEMORIO_PROJECT_ID, then package.json's name, then the directory name. User experience, agent operating knowledge, and Logic data use the sibling user.mem, agent.mem, and logic.mem files. These are separate stores, not interchangeable scopes. memory.acquire() sanitizes secret-looking knowledge before persistence and records a memory kind. Use the explicit scope, kind, and (when writing for a project other than the current working directory) sourceProject options instead of encoding routing information in applicability.

How AI activation works

Memorio does not project full identity and continuity context into an unknown runtime by default. A new carrier first passes a minimal handshake that evaluates compatibility outside the model itself.

carrier unknown → handshake → COMPATIBLE / LIMITED / INCOMPATIBLE
                         ↓
             trusted user binding when required
                         ↓
               bounded context projection

Carrier compatibility, user binding, identity, runtime, and authority remain separate. Historical memory may identify a known user, but it cannot authenticate the current speaker; changing the model or runtime may require a new handshake. Projected memory remains untrusted prior context and must be reconciled with present reality before use. See MEMORY.md and SECURITY.md for the full handshake, binding, and authority model.

Policy and authority

Memory, policy, and authority are separate: memory can never promote itself to policy, a claim never selects its own enforcement tier, and chat cannot lower a hard-precondition. memory.policy.evaluate(event) is the decision-time pull (for example artifact.write), with a privileged, authority-required write path, and memory.acquire() gates on the payload. A privileged out-of-band policy override (ADR-019) can relax the effective tier of a policy for a bounded, audited window without changing the base policy: memory.policy.override.{grant,revoke,list,effective}, CLI npx memorio policy override ... / npx memorio policy effective. See MEMORY.md and SECURITY.md for details; architectural decisions are recorded in .project/adr/013-memory-policy-authority-separation.md and .project/adr/019-privileged-policy-override.md. Remembered identity is continuity, not authentication; read paths can report governed state but cannot become privileged write paths through model interpretation. See SECURITY.md for the full authority and binding model.

Identity, codenames, and Logic

Identity composition is allowed. Identity fusion is not. See Design philosophy, point 10. Memorio's surfaces carry codenames (Scintilla, Corteccia, Dopamina, Vescicola, ...) as a symbolic identity layer: npx memorio codenames lists them, and they never affect execution. See .project/adr/014-codename-registry.md. PHASE 0 of memorio.logic is also available for structured situation/action/outcome experience and precedent selection. It is deliberately isolated from project acquired memory and is not an autonomous reasoning engine; see markdown/LOGIC.md.

Where to go next

Core

| Topic | Reference | | --- | --- | | Reactive state | markdown/STATE.md | | Persistent key/value store | markdown/STORE.md | | Observing changes | markdown/OBSERVER.md | | Structured application memory | MEMORY.md | | Portable .mem package and inspection | markdown/MEM_FORMAT.md | | Logic PHASE 0 | markdown/LOGIC.md |

Storage

| Topic | Reference | | --- | --- | | Session storage (tab-scoped) | markdown/SESSION.md | | In-memory cache | markdown/CACHE.md | | IndexedDB | markdown/IDB.md | | SQLite (sql.js / bun:sqlite) | markdown/SQLITE.md |

Sync & history

| Topic | Reference | | --- | --- | | Local-first sync & cloud | markdown/SYNC.md | | Memory attachments (linking memory entries) (proposed, not yet implemented) | markdown/MEMORY-ATTACHMENT.md | | History, undo/redo, snapshot, diff, trace | markdown/HISTORY.md | | Temporal memory: time-travel query, branching, provenance | markdown/TEMPORAL.md |

Identity, authority & security

| Topic | Reference | | --- | --- | | Identity resolution precedence (ADR-021) | .project/adr/021-identity-resolution-precedence.md | | Context resolution (ADR-022) | .project/adr/022-context-resolution.md | | Identity and behavior integrity (ADR-023) | .project/adr/023-identity-behavior-integrity.md | | Carrier handshake and authority binding (ADR-026) | .project/adr/026-carrier-handshake-and-authority-binding.md | | Limited canonical profile projection (ADR-027) | .project/adr/027-limited-canonical-profile-projection.md | | Memory / policy / authority separation (ADR-013) | .project/adr/013-memory-policy-authority-separation.md | | Privileged policy override (ADR-019) | .project/adr/019-privileged-policy-override.md | | --- |

Integrations

| Topic | Reference | | --- | --- | | React (useObserver via memorio/react) | markdown/USEOBSERVER.md | | Typed state | markdown/TYPED.md | | Schema validation | markdown/SCHEMA.md | | Pub/sub events outside React | markdown/DISPATCH.md | | Console logging middleware | markdown/LOGGER.md |

Ops & security

| Topic | Reference | | --- | --- | | Platform detection & multi-tenant context isolation | markdown/PLATFORM.md | | Classic import vs memorio/global | markdown/IMPORT.md | | Runtime introspection | markdown/INSPECT.md | | Browser DevTools | markdown/DEVTOOLS.md | | Security, encryption, threat model | SECURITY.md | | Historical internal audit (not a third-party audit) | markdown/AUDIT-REPORT.md |

Honest limitations

Memorio is upfront about what it doesn't do, so you don't find out the hard way:

• No encryption by default. Data is stored in plain text unless you explicitly turn on memorio.encryption or pass an encryptionKey. See SECURITY.md.
• Namespaces/contexts aren't a security boundary. memorio.isolate() gives you logical separation between tenants or sessions, not authorization or access control - enforce that at your application layer.
• SQLite persistence uses a journal + checkpoint strategy. Individual writes are recorded in an append-only journal (incremental); periodic checkpoints snapshot the full database. This avoids serializing the entire database on every write. The bun:sqlite backend doesn't support export() but handles persistence natively - see markdown/SQLITE.md.
• memory.context() is rule-based, not embedding-based. It ranks structured entries by recency, confidence, and type - it does not do semantic similarity search. Pair it with a vector store if your agent needs "find things like this."
• Key management is your responsibility. Memorio's encryption is client-side; it doesn't manage, rotate, or store keys for you.
• Memorio governs context, not arbitrary model behavior. It can control what is stored, admitted, projected, rejected, and authorized, but it cannot guarantee that every downstream model will interpret projected context perfectly.
• Carrier compatibility is runtime-specific. A model that is technically capable of using Memorio may still fail the identity, authority, or continuity contract. Carrier changes may therefore require a new handshake before full context is projected.

When to use something else

• A server database - for authoritative persistence, multi-user authorization, or server-side transactions.
• A dedicated secrets manager - for high-privilege credentials, encryption key management, or regulated data at rest. Memorio's encryption is client-side and key-management is your responsibility - see SECURITY.md.
• A dedicated vector database - for true embedding similarity search. Memorio manages structured memory (preferences, decisions, facts), not embeddings.

Design philosophy

1. Local first - the app stays useful when the network disappears.
2. Persistence is optional - start in memory, persist only when it adds value.
3. The cloud is optional - sync extends the local app; it doesn't define it.
4. Use the right primitive - relational data belongs in SQL, not a kv store; memory isn't the same as ordinary state.
5. Memory has meaning - confidence, source, type, scope, TTL, tags, history, status: more than "just a value."
6. Memory belongs to whoever it's about - structured and inspectable by default, encryptable with a key the vendor doesn't have to hold.
7. Global access is explicit - opt in with import 'memorio/global', or keep it explicit with named imports.
8. Tell the truth about boundaries - encryption is opt-in (not default), contexts aren't authorization, and there's no embedding search unless paired with one. (See Honest limitations above.)
9. Keep the common case tiny - state.value = 42 is a complete, valid program.
10. Identity is not runtime metadata - users and agents remain themselves when hosts, providers, or models change. Runtime information may describe where an identity is carried, but it is not persisted back into the canonical identity.
11. Memory is not authority - remembered information can inform a decision; it cannot authorize itself.
12. Authorization is current - historical identity can establish continuity, but current authority requires a trusted current binding.
13. Continuity must survive disagreement - useful memory preserves not only what was learned, but the ability to question previous conclusions.

License

MIT © Dario Passariello