mnemosyne-context
Skill3.7k starsChanged 5 months agoMITView on GitHub
Load this when working on the mnemosyne memory system — its repo, sync server, memory databases, or CI. Covers architecture, the surface/sync data model, dev workflow (tests/ruff/CI matrix), release policy, and known gotchas that are easy to get wrong. Use for any "mnemosyne" dev or devops task, or when a sync/import/recall behaves unexpectedly.
1 other project uses a version of this.
Trending
More talk lately.about the whole repository
Most recently taken up by
- AxDSan/mnemosyneword for word, first seen Oct 8, 2026
Who's talking about mnemosyne-oss/mnemosyne
- jak119/mnemosyne-docker“Bump mnemosyne-memory from 3.15.1 to 4.0.0 in the python-dependencies group”GitHub · Nov 5, 2026
- jtstothard/hermes-tiered-memory“chore(deps-dev): update mnemosyne-memory requirement from <4.0.0,>=3.14.0 to >=3.14.0,<5.0.0”GitHub · Nov 2, 2026
- l1lchucky/chronalyn“build(deps-dev): update mnemosyne-memory requirement from <4,>=3.15 to >=3.15,<5”GitHub · Nov 2, 2026
- juanmackie/mnemosyne-hermes“provider: Update mnemosyne-memory requirement from <3.16,>=3.15.1 to >=3.15.1,<4.1 in …”GitHub · Nov 1, 2026
- AxelFooley/MnemoBrain“chore(deps): update dependency mnemosyne-memory to v4.0.0b6”GitHub · Oct 20, 2026
The biggest 5 of 21 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 21
Talked about on GitHub (21 times).
On GitHub · 21
- Nov 5, 2026Bump mnemosyne-memory from 3.15.1 to 4.0.0 in the python-dependencies group — jak119/mnemosyne-docker0 reactions
- Nov 2, 2026chore(deps-dev): update mnemosyne-memory requirement from <4.0.0,>=3.14.0 to >=3.14.0,<5.0.0 — jtstothard/hermes-tiered-memory0 reactions
- Nov 2, 2026build(deps-dev): update mnemosyne-memory requirement from <4,>=3.15 to >=3.15,<5 — l1lchucky/chronalyn0 reactions
- Nov 1, 2026provider: Update mnemosyne-memory requirement from <3.16,>=3.15.1 to >=3.15.1,<4.1 in /integrations/hermes-provider — juanmackie/mnemosyne-hermes0 reactions · 1 comment
- Oct 20, 2026chore(deps): update dependency mnemosyne-memory to v4.0.0b6 — AxelFooley/MnemoBrain0 reactions
16 more on GitHub
- Oct 17, 2026[docs] Add comparison to more comparable similar projects — indigokarasu/chronicle-agent-context-and-memory0 reactions
- Oct 15, 2026fix(ai-agent): revive mnemosyne memory (patch 0.7.4 constructor, share default bank) — DaRacci/nix-config0 reactions · 1 comment
- Oct 15, 2026[bug]: memory setup stringifies list/dict defaults; accepting mnemosyne sync_roles default silently disables capture — NousResearch/hermes-agent0 reactions · 3 comments
- Oct 12, 2026[Bug] Update disables Mnemosyne: unselected KittenTTS/core ONNX 1.29 pin conflicts with embeddings — NousResearch/hermes-agent0 reactions · 5 comments
- Oct 6, 2026feat(deps): update dependency mnemosyne-hermes ( 0.5.0 → 0.7.4 ) — 1Solon/Home-Server-Configuration0 reactions
- Oct 3, 2026chore(deps): update dependency mnemosyne-memory to v4.0.0b4 — AxelFooley/MnemoBrain0 reactions · 1 comment
- Sep 29, 2026fix(docker): reconcile selected plugin dependencies before image boot — NousResearch/hermes-agent0 reactions · 3 comments
- Sep 29, 2026Investigate the mnemosyne-oss/mnemosyne naming collision and decide whether to rename — Nabzx/mnemosyne0 reactions · 1 comment
- Sep 16, 2026Update Mnemosyne entry: new org URL — scross01/awesome-hermes-agent0 reactions
- Sep 16, 2026plugin-catalog: add mnemosyne-memory — NousResearch/hermes-agent0 reactions · 10 comments
- Sep 16, 2026[Bug]: recall loop in memory context retrieval (Mnemosyne integration) — NousResearch/hermes-agent0 reactions · 2 comments
- Sep 7, 2026fix(#914): per-write author stamps on Hermes provider writes + row-level author at consolidation — Triquetra/mnemosyne0 reactions · 1 comment
- Aug 12, 2026feat: mnemosyne — long-term memory for every Sherman — evanmotovich1-web/sherman0 reactions
- Aug 6, 2026`agent_context` is hardcoded to "primary" — provider context-skip logic (cron/flush/subagent) is dead code — NousResearch/hermes-agent0 reactions · 3 comments
- Jul 21, 2026feat(memory): add mnemosyne-oss backend for local, portable agent memory — can1357/oh-my-pi0 reactions · 3 comments
- Jul 18, 2026feat(beam): wire recall_count/last_recalled into scoring — Phase 3 of upstream #289 — sventro/mnemosyne0 reactions
Other versions1 project uses a version of this.
Word for word · 1
- AxDSan/mnemosyne★ 3.7k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- no-mistakesSkill
- no-mistakesSkill
- hermes-memory-providersSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Architecture-first, and ship DONE work: Ask "does this need a version bump / is this the right layer?" before implementing.
- Very specific: line 40
Tests: use the repo venv — .venv/bin/python -m pytest tests/<file> -q.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mnemosyne context
Mnemosyne is a persistent memory system for AI agents (SQLite-backed, hybrid recall). Repo: github.com/mnemosyne-oss/mnemosyne, owned by the user (Abdias / AxDSan). It is their repo — not a third-party fork.
Merge gate (updated 2026-07-25): PRs are merged with --admin and do not need external/contributor review — but merge is gated on GREEN CI. Never merge with failing or pending required checks; re-run flaky jobs (e.g. the temporal-recall perf gate) until green, then merge.
Voice & conduct when acting for the owner
- On GitHub, you ARE AxDSan (the owner). Speak first-person with direct authority — "LGTM, merging.", "This breaks X, fix Y." Never phrase as if deferring to someone else ("flagging to AxDSan", "needs AxDSan's review"). There is no one above you to escalate to on this repo.
- Verify before asserting (importance 0.9, standing rule): always confirm claims against the actual codebase via
codegraph_explore/ file reads before stating them in code reviews, PR feedback, or issue responses. Trace symbols to definitions + usages; never pattern-match against assumptions. - Architecture-first, and ship DONE work. Ask "does this need a version bump / is this the right layer?" before implementing. Deliver tested, complete implementations — not partial work.
- Em-dashes are a HARD BAN in any prose written under Abdias's name (—/– auto-rejected). This is a personal quality standard, not a style suggestion. (Terminal/code output is exempt; this is about public-facing text.)
- "Draft" means preview, do not send. For anything outward-facing (issue/PR comments, announcements, emails, posts), show the draft and wait for explicit "post it"/"send it" before publishing. Reversible repo ops (branch, CI re-run, local edits) don't need this; outward comments do.
- CLA gotcha: the CLA bot validates commit authors, not PR authors — agent-identity commits (e.g.
Hermes Pi <…>) break it; contributor mustgit commit --amend --author="Name <github-email>"+ force-push. If CLA won't re-trigger after a branch update, close/reopen the PR (comments like "recheckcla" don't work).
Verify before trusting
Any point-in-time fact here (open issues/PRs, endpoints, versions) may be stale — confirm with gh, mnemosyne, or a fresh mnemosyne_recall before acting on it. The durable model + conventions below change slowly.
Architecture (mental model)
- BEAM is the core store. Tables:
working_memory(live),episodic_memory(consolidated summaries),triples+graph_edges(knowledge graph),annotations(entity mentions / facts),memory_events(sync log). Plusmemoria_*tables for structured recall. - Recall is hybrid: vector + FTS5 + importance (+ optional temporal boost). Weights tunable per-query / via env.
- Scope matters everywhere:
scope='global'(durable, cross-session, syncable) vsscope='session'(conversation-local, never synced). Most memories are session-scoped. - Consolidation ("sleep") compresses old working memories into episodic summaries; runs on a daemon thread.
Sync / surface model — the #1 thing people get wrong
mnemosyne sync does NOT replicate the private DB. It replicates a shared surface: a separate, dedicated DB containing only scope='global' rows tagged with a sync_surface_id. Consequences:
- Pointing sync at a private
mnemosyne.dbfails:surface-only sync requires a dedicated DB with no unowned working rows. Use a dedicated relay DB (sync-init/sync-serve --initialize-surface). - An empty surface → every sync reports 0. That's correct, not a bug.
- Push is reconciliation:
_discover_local_mutations()diffs the surface'sworking_memoryagainstsync_memory_state→ emits create/update/delete events. It does not send a hand-written event log. - Dedup is by event identity (
event_id) + a content-hash integrity guard;INSERT OR IGNOREon the event PK +known_statescheck make pull/push idempotent (retry after failure re-processes the same events safely — no duplicate memories). It does NOT dedup two different events with identical text. - Conflicts: last-writer-wins by (timestamp → importance → device_id), with v2 causal-chain resolution via
parent_event_ids. - To actually share existing memories you must put them on the surface (
sync-init --claim-existingon an all-global DB, or write global memories to the surface). To mirror an entire DB (incl. session memories) use export/import, not sync.
Dev workflow
- Local
mnemosyneCLI + MCP server run from the pipx install (~/.local/share/pipx/venvs/mnemosyne-memory), NOT the repo. Editing the repo does not affect them unless installed editable. (Some operator deployments install it editable instead, in which case repo edits do take effect; check before assuming either.) - Tests: use the repo venv —
.venv/bin/python -m pytest tests/<file> -q. Running from the repo dir makesimport mnemosyneresolve to the repo source (shadows pipx). pytest lives in.venv, not pipx. - Set
MNEMOSYNE_NO_EMBEDDINGS=1for fast test runs; embedding-dependent tests are flaky because Hugging Face rate-limits (429) theBAAI/bge-small-en-v1.5download. CI defaults to this and caches~/.hermes/cache/fastembed. tests/test_temporal_recall.py::...::test_performance_overheadis a flaky wall-clock gate (<10ms). A single-version red on it is almost always load noise — re-run the job.- Ruff: pinned
ruff==0.15.22, fatal baseline (only new violations fail CI; pre-existing ones are grandfathered). Lint changed files ephemerally:pipx run ruff==0.15.22 check <files>. - CI matrix:
test (3.10/3.11/3.12/3.13)+lint+build+docs-check+CodeRabbit+license/cla. - Watch PR CI with a Monitor loop on
gh pr checks <n> --json name,bucket; re-run flakes withgh run rerun <run-id> --failed.
Release policy
- Strict SemVer from v3.1.2 onward (MAJOR=breaking, MINOR=feature, PATCH=bugfix).
RELEASING.mddocuments it;.githooks/pre-pushenforces tag format + version bump. - Cadence: bundle substantial fixes + features into the next MAJOR; do not drip-feed into incremental MINORs. Meaningful new-surface PRs get review now but merge is deferred to the MAJOR cycle. MINORs ship only when enough additive opt-in features accumulate.
- Local pipx installs track PyPI releases — a merged fix isn't in your local CLI until a release ships (or you reinstall from source). Don't
pipx reinstallfrom PyPI expecting an unreleased fix; it silently reverts it.
DevOps
The deployment topology (sync server, dashboard, bot, and the host they run on) is operator-specific and is not documented in this public repository. Hosts, addresses, service definitions and credential paths live in the operator's private runbook.
What is safe to know here: the sync server is mnemosyne sync-serve bound to
loopback and reverse-proxied; it serves /sync/pull|push|status and /healthz,
and it requires a dedicated relay DB rather than a private mnemosyne.db. The
dashboard is a read-only UI on a separate port and is not a sync server, so
pointing sync_remote at it 404s on every /sync/* route.
Contributor norms
Review-routing conventions name individuals and are therefore kept in the operator's private notes rather than here. What is safe to state publicly: the merge gate is green CI, external review is not required, and the CLA bot validates commit authors rather than PR authors.
Known gotchas / decided designs
- Config precedence (#482):
config.yaml> env > default. Runtime readsMnemosyneConfig.get()directly — no YAML→env bridge /apply_to_env(). Many config keys need a process restart to take effect. - No schema-level FKs (#503 closed):
PRAGMA foreign_keys=ONbroke 22 tests that intentionally create orphan rows. Do orphan cleanup at app level during sleep/consolidation instead. - Beam access is lock-serialized (#498/#520):
_beam_access_lockguards Beam/SQLite between main thread and the auto_sleep daemon (a WAL checkpoint mid-statement caused a SEGV). Don't introduce unguarded cross-thread Beam access. - Import idempotency (#538, merged):
AnnotationStore.import_allnow skips(memory_id,kind,value)UNIQUE collisions instead of aborting the whole import —mnemosyne importis safely re-runnable. - Security: sync auth is bearer API key or JWT; a past JWT-signature-bypass was fixed — signatures are verified with
hmac.compare_digest, alg pinned HS256. Sync HTTP server is off by default in the Hermes plugin.
CLI cheat-sheet
mnemosyne export [file.json] [--include-sync-events] # read-only dump (runs on ANY arg — no --help!)
mnemosyne import <file.json> [--force] # merge into local DB (idempotent for memories)
mnemosyne sync --db-path <surface.db> --remote <url> --api-key-file <f> --mode bidirectional
mnemosyne sync-init --db-path <surface.db> [--claim-existing --yes]
mnemosyne sync-serve --db-path <relay.db> --host 127.0.0.1 --port <p> --api-key-file <f> [--initialize-surface]
mnemosyne sync-status --db-path <surface.db> [--remote <url>] [--api-key-file <f>] [--json]
mnemosyne config set <key> <value> # note: many keys need a restart⚠️ export/remember treat --help as a positional arg (dumps / stores it). Use mnemosyne --help for the top-level list.
Code navigation
This repo is CodeGraph-indexed (.codegraph/) — prefer codegraph_explore "<symbols or question>" over grep/read for understanding or before editing; one call returns verbatim source + call paths + blast radius. Sync internals live in mnemosyne/core/sync.py, server in sync_server.py, store in beam.py, annotations/triples in core/annotations.py + core/triples.py.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

