Meminisse

This tool helps you give Codex always-on persistent memory across sessions. It stores durable global and workspace context so that Codex can recall prior work, preferences, decisions, and repeatable procedures when a session, project, or task starts.

Project status: actively maintained

Basic functionality

Meminisse is intended for use by Codex users who want memory that survives context limits, restarts, and work across multiple repositories. It is meant to help those users keep track of durable context without copying the same background information into every new session.

Meminisse stores memory records as JSONL files and retrieves them with a small cue-based scoring system. It uses memory kinds such as decision, fact, procedure, preference, and event to separate the intent of each record while still searching all relevant memory together.

Meminisse uses project-local and user-global storage to do persistent recall. It takes memory text from CLI commands and Codex skill workflows and uses it to write structured records with summaries, tags, entities, paths, timestamps, confidence, schema version, and status fields. For more details about the technical implementation, see the developer documentation.

What Meminisse does not do

This tool cannot increase the model context window. It does not make Codex automatically know every stored memory unless the memory is recalled and brought back into the active conversation.

Meminisse does not provide semantic vector search, hosted sync, or multi-user conflict resolution. It supports optional at-rest encryption for JSONL memory records with a key supplied from an environment variable. It also blocks common secret patterns before writing memory records, but you should still avoid storing API keys, passwords, private keys, .env values, or other credentials.

Prerequisites

Before using this tool, you should be familiar with:

• The basics of running shell commands in a Codex workspace.
• How Codex plugins, skills, and local marketplaces are structured.
• Basic JSON and Markdown files.

You should have:

• Node.js available on your PATH.
• A local shell that can run Node.js and npm commands on macOS, Linux, Windows, or another Node-supported platform.
• Permission to write to the current repository.
• Permission to write to ~/.codex/plugins, ~/.codex/skills, ~/.codex/memories, and ~/.agents/plugins for personal Codex installation.

How to use Meminisse

Install Meminisse for personal Codex use

1. Install Meminisse from npm.

   npm install -g meminisse

2. Install the Codex plugin, skill, and personal marketplace entry.

   meminisse install --local --force

3. Confirm that the installer prints paths under ~/.codex/plugins/meminisse, ~/.codex/skills/meminisse, and ~/.agents/plugins/marketplace.json.

4. Restart Codex.

5. Open the plugin directory in Codex.

6. Select the personal marketplace named Local Plugins.

7. Install or enable Meminisse.

After installation, Codex CLI includes the Meminisse skill in the model-visible skill list. The skill description tells Codex to use Meminisse for every session, project, and task unless the user explicitly opts out. You can verify this with:

codex debug prompt-input "New task" | rg "meminisse"

Initialize memory storage

1. Initialize project and global memory directories.

   meminisse init --scope all

2. Confirm that project memory exists under:

   .meminisse/memory/

3. Confirm that global memory exists under:

   ~/.codex/memories/meminisse/memory/

Project initialization also ensures .meminisse/ is ignored in .gitignore. If .npmignore, .dockerignore, or .remarkignore already exist, Meminisse adds the project memory directory there too.

Remember durable context

1. Choose the kind of memory to store.

   1. Use decision for durable choices and rationale.
   2. Use procedure for repeatable workflows or commands.
   3. Use preference for user preferences that should apply across sessions.
   4. Use event for a bounded task or session summary.

2. Write the memory.

   meminisse remember --kind decision "Use npm for this repository."

3. Replace an older memory with --supersedes when a decision changes.

   meminisse remember --kind decision --supersedes mem_20260412_abcd123456 "Use Node's built-in test runner."

4. Store global preferences with global scope.

   meminisse remember --kind preference --scope global "Prefer concise status updates."

Meminisse skips exact duplicate active memories unless you pass --force. It also blocks likely secrets such as API keys, tokens, password assignments, private key blocks, credential URLs, .env file attachments, and common access-key formats.

Recall relevant memory

1. Query memory before answering a question or making a change.

   meminisse recall "package manager and prior decisions"

2. Use global installation from any workspace after personal install.

   meminisse recall "recent work and preferences"

3. Use JSON output when integrating with another script.

   meminisse recall --json "deployment procedure"

4. Limit terminal output for token efficiency.

   meminisse recall --mode ids --max-chars 1200 --threshold 4 "deployment procedure"

Recall modes are summary, full, and ids. Terminal recall defaults to summary, limits output with --max-chars 4000, and only returns active memories. Recall uses weighted lexical scoring with BM25-style term-frequency normalization across summaries, bodies, tags, entities, and paths. Matching records also receive lightweight recall telemetry with recall_count and last_recalled_at.

Inject startup memory

1. Print high-priority memories for a session startup hook.

   meminisse inject --scope all

2. Limit the injected kinds when a hook should stay narrow.

   meminisse inject --scope all --kinds preference,procedure --max-chars 2000

inject is deterministic hook output for preferences, procedures, and decisions. It is intended for agent/session startup integration where a runtime can execute a command before the first model turn.

Encrypt memory records

1. Set an encryption key in the environment used by Meminisse.

   export MEMINISSE_ENCRYPTION_KEY="replace-with-a-long-local-secret"

2. Enable encryption for project and global memory.

   meminisse encryption enable --scope all

3. Check encryption status.

   meminisse encryption status --scope all

Encrypted memory records are stored as AES-256-GCM envelopes in the primary JSONL files. The key is not written to disk; the same environment variable must be available for later recall, list, status, compact, and review operations.

Inspect and retire memory

1. List active records without a search query.

   meminisse list --scope all --limit 20

2. Include records that were superseded or deleted.

   meminisse list --status all

3. Filter by kind or emit JSON for scripts.

   meminisse list --kind decision --json

4. Retire an outdated active memory by ID.

   meminisse forget mem_20260412_abcd123456 --reason "Outdated project decision."

forget marks matching active records with status: "deleted" instead of removing JSONL rows. Deleted records are excluded from normal recall but remain inspectable with meminisse list --status deleted.

Check and review memory health

1. Check local installation and storage paths.

   meminisse doctor

2. Emit machine-readable checks for scripts.

   meminisse doctor --json

3. Review active records for maintenance issues.

   meminisse review

doctor checks the CLI version, package metadata, installed plugin, installed skill, marketplace entry, memory paths, and ignore-file protection. review reports stale version memories, exact duplicate active records, and broken project-local path references. Review is report-only; it does not change memory records.

Run local benchmarks

1. Run the deterministic benchmark suite.

   npm run benchmark

2. Emit JSON output for scripts.

   npm run benchmark -- --json

3. Measure answer quality for a Codex model.

   npm run benchmark -- --model gpt-5.4 --model-limit 2

The benchmark runner creates isolated temporary workspaces and HOME directories, writes known memory fixtures through the real CLI, then measures recall quality, lifecycle leakage, and review signals. It uses no external datasets, non-Codex model providers, or the user's real memory stores. Model-backed benchmark runs are optional and use codex exec --model <model>.

Attach supporting files

1. Attach a file to the current project memory store.

   meminisse attach ~/Downloads/error-screenshot.png --kind evidence --tags bug,api

2. Attach a file with a custom title.

   meminisse attach ~/Downloads/client-notes.md --kind reference --title "Client notes"

Attachments are copied under .meminisse/attachments/YYYY/MM/<slug>/. Each attachment gets an original file, metadata.json, and note.md. Meminisse writes a memory record that points at those project-local paths, so future recall can find the supporting file. By default, attachments are copied and the original source file is left alone. Pass --move only when you explicitly want to remove the original source file after copying it into .meminisse. Meminisse refuses likely secret attachments, including .env files, unless you pass --allow-secret.

Consolidate memory

1. Run consolidation after meaningful work or after several memory records have been added.

   meminisse compact --scope all

2. Archive inactive JSONL rows while consolidating when long-lived memory files need cleanup.

   meminisse compact --scope all --prune

   Pruning moves deleted and superseded records into .meminisse/memory/archive/<timestamp>/ or the matching global archive directory. Active records stay in the primary JSONL files.

3. Review the generated summaries.

   1. Project summary:

      .meminisse/memory/consolidated.md

   2. Global summary:

      ~/.codex/memories/meminisse/memory/consolidated.md

4. Use the status command to confirm active record counts.

   meminisse status

5. Use verbose status when you need lifecycle and kind breakdowns.

   meminisse status --verbose

Troubleshooting

The plugin does not appear in Codex after installation

• Restart Codex after changing a marketplace or plugin folder.
• Check that ~/.agents/plugins/marketplace.json exists and points to ./.codex/plugins/meminisse.
• Check that ~/.codex/plugins/meminisse/.codex-plugin/plugin.json exists.

Recall returns no relevant memories

• Confirm that memory records exist with:

  meminisse status

• Try a broader query with fewer terms.

• Confirm that you wrote records to the expected scope. Project memory is stored under .meminisse/memory; global memory is stored under ~/.codex/memories/meminisse/memory.

The local installer does not update an existing installation

• Run the installer with --force:

  meminisse install --local --force

The marketplace path points to an old plugin location

• Re-run the local installer with --force.

• Verify that the Meminisse entry in ~/.agents/plugins/marketplace.json uses:

  {
    "source": {
      "source": "local",
      "path": "./.codex/plugins/meminisse"
    }
  }

How to get help and report issues

• Report issues by opening an issue in the repository where Meminisse is published.
• Ask questions in the same repository so context and answers stay attached to the project.

Developer documentation

Technical implementation

This tool uses Node.js built-in modules to implement a dependency-free CLI. It depends on fs, path, os, and crypto because it writes JSONL records, resolves local and global storage paths, and creates stable short IDs for memory records.

Meminisse stores records in append-only JSONL files. New records include schema_version so future readers can handle format changes without guessing. Recall tokenizes the query and scores active records using weighted BM25-style lexical scoring across summary text, body text, tags, entities, and paths, then applies small confidence, status, kind, and recency boosts. Recall supports summary, full, and id-only output modes plus relevance thresholds and character budgets for token efficiency. Recall also updates lightweight per-record telemetry fields so later status and review work can see which records are used. Encryption support uses AES-256-GCM with a key supplied by environment variable. Consolidation reads active records and writes a Markdown summary plus an index.json file. compact --prune can archive deleted and superseded records out of primary JSONL files.

Memory lifecycle controls include duplicate detection, secret detection, listing, health checks, review reports, soft deletion, and --supersedes handling. When a new memory supersedes an older record, the older record is rewritten with status: "superseded" and excluded from normal recall. When a memory is forgotten, it is rewritten with status: "deleted" and remains available for audit-style inspection through meminisse list --status deleted.

Project attachments are copied into .meminisse/attachments. Each attachment has a small Markdown note and JSON metadata file, and Meminisse writes a normal memory record with paths to those files.

Benchmarks live under benchmarks/ and run with npm run benchmark. They exercise deterministic local fixtures through the real CLI and report recall quality, lifecycle safety, review signal quality, and optional Codex model answer/citation accuracy.

Code structure

The bin/meminisse.js file is a small npm executable launcher.

The src directory contains the CLI implementation: src/cli.js dispatches commands, src/commands/ contains individual command handlers, src/memory/ contains storage and recall logic, src/security/ contains encryption and secret detection, src/system/ contains path and platform helpers, and src/core/ contains shared CLI utilities.

The skills/meminisse directory contains the Codex skill instructions that tell Codex when to recall memory and when to write durable memory.

The .agents/plugins/marketplace.json file exposes Meminisse through a repo-scoped marketplace for local testing.

The .meminisse/memory directory contains this repository's project memory records. It is runtime data, not plugin source code. Meminisse automatically keeps .meminisse/ out of Git and, when the files exist, npm package inputs, Docker build contexts, and Remark inputs.

Local development

Set up

How to set up development environment:

1. Clone or open this repository.

   1. Confirm Node.js is available:

      node --version

   2. Confirm npm is available:

      npm --version

Install

How to install:

1. Install Meminisse into the personal Codex plugin location.

   1. From a repository checkout, run:

      npm run install:local -- --force

   2. Or, after global npm installation, run:

      meminisse install --local --force

   3. Restart Codex so it reloads the personal marketplace.

Configure

How to configure:

1. Edit ~/.agents/plugins/marketplace.json if you want to rename the personal marketplace.

2. Keep the Meminisse plugin entry pointed at ./.codex/plugins/meminisse.

3. Use ~/.codex/memories/meminisse/memory for global memory and .meminisse/memory for workspace memory.

4. For npm-installed usage, run meminisse directly from your shell.

Build and test

How to build and run locally:

1. No build step is required.

   1. Run the CLI directly:

      meminisse status --verbose

   2. Or run the installed personal copy:

      meminisse status

How to run tests:

1. Run the integration test suite.

   1. Execute:

      npm test

   2. Confirm the CLI and installer tests pass.

Debugging

• meminisse: Scope must be project, global, or all.

  • The --scope value is invalid. Use project, global, or all.

• meminisse: Unsupported kind

  • The --kind value is invalid. Use event, session, fact, decision, procedure, preference, or note.

• No relevant memories found.

  • The query did not match any active memory records. Use broader terms or add durable memory with remember.

• Missing required path

  • The local installer cannot find the plugin source directory. Run the installer from this repository after confirming .codex-plugin, bin, src, and skills exist.

How to contribute

The Meminisse maintainers welcome focused contributions.

• Bug fixes for CLI behavior, storage handling, or marketplace installation.
• Improvements to recall scoring and consolidation.
• Documentation improvements.
• Tests for memory parsing, scoring, and installer behavior.

Contribution process

Before contributing, read the existing coding style in src/commands and the supporting category folders under src. Use clear file headers and JSDoc comments for script files.

1. Create a focused branch.

   1. Keep changes scoped to one behavior or documentation area.
   2. Avoid unrelated formatting churn.

2. Make the change.

   1. Add or update JSDoc for modified functions.

   2. Run:

      npm test

3. Verify installation if plugin packaging changed.

   1. Run:

      npm run install:local -- --force

   2. Restart Codex and confirm the marketplace entry still appears.

License

Meminisse is licensed under the MIT License. See LICENSE.