Portable, local-first memory for coding agents.
Save preferences, project decisions, corrections, and trusted procedures once; recall them from Claude Code, Codex, Pi, Gemini CLI, or OpenCode without using a hosted memory service. SQLite is durable truth. Search and graph projections are local and rebuildable. Stored content is prior data, never instruction authority.
Important
This branch documents source version 0.10.1. Use released binaries only
from the matching Git tag and GitHub Release after its workflow completes
successfully. Run mem --version; the CLI, bundled skill, and documentation
must remain in exact release lockstep.
Quick start · Capabilities · Evidence · Documentation
This complete save/query/prime example never touches an existing store:
demo_store="$(mktemp -d "${TMPDIR:-/tmp}/mnemark-demo.XXXXXX")"
trap 'rm -rf -- "$demo_store"' EXIT
mem --home "$demo_store" init
mem --home "$demo_store" save \
--type preference --name concise_answers --scope global \
--source manual --user-confirmed --tags '["style:concise"]' \
--content 'Trigger: user-facing replies. Action: answer concisely. Why: explicit preference.'
mem --home "$demo_store" query "concise replies" --format compact
mem --home "$demo_store" --read-only primeFor a real store, inspect the resolved target before initialization:
mem config show
mem initWith mise:
mise use --global --pin github:NeoHsu/mnemark@latest
mem --versionFor checksum-verified shell and PowerShell installers, direct release archives, SBOMs, and provenance verification, follow Getting Started.
Preview one platform before writing user-level policy, skill, or hook files:
mem setup list
mem setup pi --dry-run
mem setup pi
mem doctor --platform piReplace pi with claude-code, codex, gemini-cli, or opencode only for a
platform you use. Agent policy and Claude Code's session hook enforce the same
session sequence: exact compatibility check, process-level read-only priming,
and fail-closed continuation without memory when either gate fails.
| Without mnemark | With mnemark |
|---|---|
| Knowledge is tied to one agent platform | One private store serves supported agents |
| Session context disappears | Bounded priming restores explicit prior data |
| Search returns isolated text matches | Focused recall can include evidence-bearing relationships |
| Procedures remain in old chats | Validated workflow memories are searchable runbooks |
| Backups and transfer are opaque | SQLite snapshots, bundles, checksums, and private Git are operator-controlled |
| Automation guesses side effects | Versioned schemas and parsed operation effects are discoverable |
The agent keeps judgment and the user keeps authority. mem performs
deterministic storage, retrieval, validation, and versioning; it never executes
workflow commands or silently promotes stored text into instructions.
supported coding agents
|
v
mem CLI
|
v
SQLite durable source
| | |
v v v
Tantivy graph workflows,
search projection artifacts, bundles
(rebuildable) (rebuildable)
Runtime-store discovery is always:
--home -> MNEMARK_HOME -> user config knowledge_home -> ~/.mnemark
Source checkouts and executable parents are never selected implicitly. Reads do not initialize or migrate a store.
Unless a session hook already injected a delimited mnemark context block, the first two memory invocations are:
mem --json-errors contract --skill-version 0.10.1
mem --read-only primeThen:
- do the task with the store structurally read-only;
- query only when primed context is insufficient;
- load a workflow for a recurring procedure;
- at work-unit completion, save confirmed corrections, decisions, and reusable
procedures as
Trigger / Action / Why; - preview synchronization with
mem sync --dry-run; - never pass
--pushwithout explicit approval.
The exact agent policy, target checks, conditional-effect rules, and mutation boundaries live in the bundled skill and are installed from the same release as the CLI.
Tantivy provides lexical and fuzzy retrieval. SQLite applies scope, lifecycle, trust, confidence, and deterministic reranking. Focused priming may add bounded relationship context from the local graph projection.
mem --read-only query "release safety" --scope auto --format compact
mem operation inspect --store-exists -- prime --focus "release safety"
mem prime --focus "release safety"
mem graph path release_policy release_runbook --format compactInspect conditionally mutating invocations before use. Global --read-only
blocks durable, rebuildable, output-file, and network effects before mutation.
See Graph Memory and Runtime Model.
Workflow memories are validated procedure data. mem finds, validates, renders,
and records them; the calling agent executes approved steps.
mem workflow find release --scope auto
mem workflow show release_runbook --checklist
mem workflow validate release_runbook --check-artifacts --repo .Repository-specific helpers stay under repository scripts/. Cross-project
helpers may be registered as private-store artifacts. Validation checks paths,
regular files, checksums, and executable intent without running helpers.
See Workflows.
mem retro daily
mem retro weekly --limit 200
mem --read-only reconcile --scope autoRetrospectives emit read-only review bundles; they do not schedule themselves or read platform logs. Reconciliation checks remembered filesystem and command claims without executing them.
mem bundle export mnemark-store.tgz
mem bundle inspect mnemark-store.tgz
mem sync --dry-run
mem syncSync checkpoints the store locally and may fetch a configured private remote;
network push remains impossible unless --push is explicit. Same-name semantic
conflicts become pending ambiguities rather than silent overwrites.
Stores and bundles are plaintext. Use private storage, trusted transfer channels, and disk or volume encryption where confidentiality matters.
Automation does not need to scrape help text:
mem contract
mem schema list
mem operation list
mem operation inspect -- query "release notes"
mem --read-only query "release notes"mem contractis store-independent.mem schema list|printexposes bundled JSON Schemas.mem operation list|inspectreturns stable leaf operation IDs and exact store/file/network effects.--read-onlyorMNEMARK_READ_ONLY=trueenforces the parsed effect decision.--max-bytesorMNEMARK_MAX_BYTESrejects oversized stdout before partial publication.--json-errorsemits versioned typed error envelopes.
See Compatibility and JSON Contracts.
The CLI and bundled skill use exact release lockstep. For an exact-version manual install:
npx skills add https://github.com/NeoHsu/mnemark/tree/v0.10.1 --skill mnemark
mem --json-errors contract --skill-version 0.10.1For development from a local checkout:
npx skills add ./skills/mnemarkmem setup <platform> remains preferred because the binary embeds and verifies
its exact skill package.
| Evidence | Boundary |
|---|---|
| Published release | v0.9.0 points to its own release commit; it is not evidence for this main revision |
| Supported store | One operating-system user, private store, up to 10,000 memories |
| Published latency baseline | Retained v0.8.0 Apple M2 Max report; not a cross-machine SLO |
| Current source gates | Formatting, tests, security, retrieval, recovery, binary-size, and benchmark checks are configured locally and in CI |
| Agent behavior | Synthetic fixtures validate the evaluator; no retained live cross-agent matrix is published |
| Capacity canary | Retained 100,000-memory correctness run; not a support claim |
| Artifact matrix | Five configured targets across macOS, Linux, and Windows |
| Supply chain | Archive/installer checksums, native archive execution, CycloneDX SBOM, and GitHub provenance configuration |
A local pass does not establish qualification for an unpushed commit. Release evidence belongs to the exact commit and artifacts that produced it. See Evaluation, Performance, and Production Operations.
The qualified deployment profile is deliberately narrow:
- one operating-system user per private store;
- explicit backup-first migrations and no automatic downgrade;
- private, access-controlled storage and trusted Git/bundle channels;
- host-level encrypted storage for confidential memory.
Bundle hashes detect corruption, not publisher identity. Secret scanning is
defense in depth, not DLP. Unix permissions are enforced as 0700/0600;
Windows user-only ACL verification must be performed with platform tooling.
Read Security before operating a real store.
| Goal | Start here |
|---|---|
| Install and save the first memory | Getting Started |
| Understand the system | Overview |
| Inspect discovery, effects, and layout | Runtime Model |
| Use workflows, artifacts, bundles, and retrospectives | Workflows |
| Understand relationship-aware recall | Graph Memory |
| Integrate automation | Compatibility and JSON Contracts |
| Operate or recover a store | Production Operations and Security |
| Evaluate retrieval or agent policy | Evaluation and Performance |
| Change the repository | Agent Reference, Development, and Contributing |
| Understand architectural decisions | Architecture and ADRs |
The complete task-oriented index is docs/README.md.
Agents must read docs/agent-reference.md before
changing this repository.
mise install
mise run check:prDo not use a real memory store in tests. See Development, Contributing, and Changelog.