{"id":48606471,"url":"https://github.com/urmzd/mnemonist","last_synced_at":"2026-04-19T21:13:13.104Z","repository":{"id":346920286,"uuid":"1192155740","full_name":"urmzd/mnemonist","owner":"urmzd","description":"An open ecosystem for tool-agnostic AI agent memory","archived":false,"fork":false,"pushed_at":"2026-04-16T04:43:13.000Z","size":1519,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T05:46:18.022Z","etag":null,"topics":["agent-memory","ai-memory","llm","rust","semantic-search"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urmzd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-26T00:13:13.000Z","updated_at":"2026-04-16T04:43:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/urmzd/mnemonist","commit_stats":null,"previous_names":["urmzd/llmem","urmzd/mnemonist"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/urmzd/mnemonist","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fmnemonist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fmnemonist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fmnemonist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fmnemonist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urmzd","download_url":"https://codeload.github.com/urmzd/mnemonist/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fmnemonist/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32022790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-memory","llm","rust","semantic-search"],"created_at":"2026-04-09T00:04:31.279Z","updated_at":"2026-04-19T21:13:13.092Z","avatar_url":"https://github.com/urmzd.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003emnemonist\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    An open ecosystem for tool-agnostic AI agent memory.\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd/mnemonist/issues\"\u003eReport Bug\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"spec/mnemonist.md\"\u003eSpecification\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/mnemonist\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/mnemonist\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/urmzd/mnemonist\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"showcase/mnemonist-demo.gif\" alt=\"mnemonist demo\" width=\"760\"\u003e\n\u003c/p\u003e\n\n## Contents\n\n- [Features](#features)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Benchmarks](#benchmarks)\n- [Testing](#testing)\n- [Agent Skill](#agent-skill)\n- [License](#license)\n\n## Features\n\n- **Cognitive CLI** — commands named after memory processes: `memorize`, `remember`, `note`, `learn`, `consolidate`, `reflect`, `forget`\n- **Two-level memory** — project (`~/.mnemonist/{project}/`) and global (`~/.mnemonist/global/`)\n- **Working memory inbox** — capacity-limited staging area (default 7 items) with attention scoring; items promoted to long-term memory via `consolidate`\n- **Memory metadata** — strength, access count, last accessed, source tracking; Hebbian reinforcement on retrieval\n- **Plain markdown** with YAML frontmatter — human-readable, git-friendly\n- **Typed memories** — user, feedback, project, reference\n- **Local embedding** — `candle` crate with `all-MiniLM-L6-v2` (384-dim, CPU/CUDA); no external server needed; model downloads from HuggingFace Hub on first use\n- **Layered graph** — three HNSW layers: code (`.code-index.hnsw`), project memory (`.memory-index.hnsw`), and global memory; inter-layer edges via `refs` frontmatter field\n- **Pluggable code chunking** — `ChunkingStrategy` trait with built-in `ParagraphChunking` (blank-line boundaries) and `FixedLineChunking` (sliding window with overlap); no tree-sitter dependency\n- **Cross-layer recall** — `remember` searches memory and code indices in parallel with blended relevance scoring (semantic + temporal); follows `refs` edges to surface referenced code chunks\n- **Consolidation** — `consolidate` promotes inbox items, decays stale memories, and re-embeds\n- **Fuzzy forget** — `forget` resolves partial and suffix matches so you don't need the full filename\n- **Embedding quality metrics** — `learn` reports anisotropy and similarity_range after indexing\n- **TurboQuant** — optional vector quantization (1-4 bit) for compact embedding storage\n- **JSON-first** — stdout for structured JSON, stderr for UX; pipe-friendly\n- Works with Claude Code, Codex, Gemini, Copilot, Cursor, or any AI tool\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/urmzd/mnemonist/main/install.sh | sh\n```\n\n\u003c!-- Rust developers can also install from source with `cargo install mnemonist-cli`. --\u003e\n\n### Hardware acceleration\n\nPre-built binaries run on CPU with pure Rust matmuls — functional, but large batch operations like `learn` are slower than accelerated builds. If you have a Rust toolchain, you can build from source with hardware acceleration:\n\n```bash\n# macOS — Apple's Accelerate BLAS (~2x faster embedding throughput)\ncargo install mnemonist-cli --features accelerate\n\n# Linux/Windows with an NVIDIA GPU\ncargo install mnemonist-cli --features cuda\n```\n\n## Quick Start\n\n```bash\n# 1. Install\ncurl -fsSL https://raw.githubusercontent.com/urmzd/mnemonist/main/install.sh | sh\n# Or, if you have a Rust toolchain: cargo install mnemonist-cli\n\n# 2. Ingest the codebase — auto-creates ~/.mnemonist/{project}/ and embeds source files\nmnemonist learn .\n\n# 3. Memorize long-term knowledge\nmnemonist memorize \"prefer Rust for CLI tools\" -t feedback\nmnemonist memorize \"deep Go expertise, new to React\" -t user\n\n# 4. Jot quick notes into the working memory inbox\nmnemonist note \"look into async runtime choices\"\nmnemonist note \"check Linear project INGEST for pipeline bugs\"\n\n# 5. Consolidate — promote inbox to long-term memory, decay stale items, re-embed\nmnemonist consolidate\n\n# 6. Recall — semantic + text search across memories and code\nmnemonist remember \"rust async patterns\"\n\n# 7. Review everything\nmnemonist reflect --all\n\n# 8. Forget something you no longer need (fuzzy name matching)\nmnemonist forget prefer-rust\n```\n\n## Usage\n\n### Memory Levels\n\n| Level | Location | Scope |\n|-------|----------|-------|\n| Project | `~/.mnemonist/{project}/` | Per-repo corrections, decisions |\n| Global | `~/.mnemonist/global/` | Cross-project preferences, expertise |\n\nProject memory takes precedence over global when they conflict.\n\n### Memory Types\n\n| Type | When | Example |\n|------|------|---------|\n| `user` | Expertise, preferences | \"Deep Rust knowledge, new to React\" |\n| `feedback` | Corrections, validated approaches | \"Never mock the database in tests\" |\n| `project` | Repo-specific context (project-level only) | \"Auth rewrite driven by compliance\" |\n| `reference` | External resource pointers | \"Bugs tracked in Linear project INGEST\" |\n\n### CLI at a glance\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"showcase/cli-help.gif\" alt=\"mnemonist --help\" width=\"760\"\u003e\n\u003c/p\u003e\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `mnemonist memorize \"\u003cpoint\u003e\" [-t type] [-n name]` | Deliberately encode a point into long-term memory (auto-embeds) |\n| `mnemonist note \"\u003cpoint\u003e\"` | Jot a quick note into working memory inbox |\n| `mnemonist remember \"\u003cask\u003e\" [--budget N] [--level both]` | Recall memories by cue — searches memory and code indices in parallel with blended relevance scoring, follows refs |\n| `mnemonist learn [path] [--attend glob] [--capacity N]` | Ingest a codebase; chunks files with `ParagraphChunking`, embeds into `.code-index.hnsw`, reports quality metrics |\n| `mnemonist consolidate [--dry-run]` | Promote inbox items, decay stale memories, re-embed into `.memory-index.hnsw` |\n| `mnemonist reflect [--all] [--global]` | Introspect — review memories and inbox contents |\n| `mnemonist forget \u003cfile\u003e` | Deliberately forget a memory (supports fuzzy/suffix name matching) |\n| `mnemonist config init` | Create default config file |\n| `mnemonist config show` | Show current configuration |\n| `mnemonist config get \u003ckey\u003e` | Get a config value (dot-notation) |\n| `mnemonist config set \u003ckey\u003e \u003cvalue\u003e` | Set a config value |\n| `mnemonist config path` | Print config file path |\n\nAll commands output JSON to stdout (`{\"ok\": true, \"data\": {...}}`).\n\n### Working Memory (Inbox)\n\nThe inbox is a capacity-limited staging area modeled after human working memory (default capacity: 7). Items enter via `note` (manual) or `learn` (code ingestion) and are scored by attention:\n\n- Items are sorted by attention score; lowest-scored items are evicted at capacity\n- `consolidate` promotes inbox items to long-term memory and clears the inbox\n- Stored in `.inbox.json` alongside memory files\n\n### Consolidation\n\n`mnemonist consolidate` runs a sleep-like consolidation cycle:\n\n1. **Promote** — inbox items become long-term memories with type and strength\n2. **Decay** — memories not accessed within `consolidation.decay_days` (default 90) and below `protected_access_count` (default 5) are pruned\n3. **Re-embed** — all surviving memories are re-embedded for fresh semantic search\n\nUse `--dry-run` to preview what would change.\n\n### Memory Metadata\n\nEach memory file tracks cognitive metadata in its frontmatter:\n\n| Field | Description |\n|-------|-------------|\n| `strength` | Consolidation strength (increases on survival) |\n| `access_count` | Retrieval count (Hebbian reinforcement) |\n| `last_accessed` | ISO 8601 timestamp of last retrieval |\n| `created_at` | When the memory was first created |\n| `source` | How it was created: `memorize`, `note`, `learn`, `consolidation` |\n| `consolidated_from` | Original files if created via merge |\n| `refs` | Inter-layer edges — code chunk IDs or memory filenames this memory links to |\n\n### Configuration\n\nLayered config: `~/.mnemonist/mnemonist.toml` (global default, created with `mnemonist config init`) + `./mnemonist.toml` at the project root (per-project overrides; missing fields inherit).\n\n```toml\n[storage]\nroot = \"~/.mnemonist\"\n\n[embedding]\nprovider = \"candle\"\nmodel = \"all-MiniLM-L6-v2\"\n\n[recall]\nbudget = 2000\npriority = [\"feedback\", \"project\", \"user\", \"reference\"]\nexpand_refs = true\nmax_ref_expansions = 3\n\n[index]\nmax_lines = 200\n\n[code]\nlanguages = [\"rust\", \"python\", \"javascript\", \"go\"]\nmax_chunk_lines = 100\n\n[inbox]\ncapacity = 7\n\n[consolidation]\ndecay_days = 90\nmerge_threshold = 0.85\nprotected_access_count = 5\nmax_memories = 200\n\n[quantization]\nenabled = false\nbits = 2\nalgorithm = \"mse\"\ntemporal_weight = 0.2\n```\n\nUse `mnemonist config set embedding.model all-MiniLM-L6-v2` to change values.\n\nSee the full [Specification](spec/mnemonist.md) for details on file format, dynamic loading, precedence rules, and integration guides.\n\n## Benchmarks\n\n\u003c!-- fsrc src=\"docs/benchmarks.md\" --\u003e\n### Distance Functions\n\n| Function | 32-d | 128-d | 384-d |\n|---|---|---|---|\n| `cosine_similarity` | 12 ns | 59 ns | 207 ns |\n| `dot_product` | 4 ns | 28 ns | 120 ns |\n| `l2_distance_squared` | 5 ns | 30 ns | 125 ns |\n| `normalize` | 18 ns | 82 ns | 239 ns |\n\n### HNSW Index (500 vectors, dim=32)\n\n| Operation | Time |\n|---|---|\n| Build (500 inserts) | 32.7 ms |\n| Search top-1 | 15.2 µs |\n| Search top-10 | 15.2 µs |\n| Search top-50 | 15.2 µs |\n| Save to disk | 91 µs |\n| Load from disk | 85 µs |\n\n### IVF-Flat Index (500 vectors, dim=32)\n\n| Operation | Time |\n|---|---|\n| Train (k-means, 16 clusters) | 2.2 ms |\n| Search top-1 | 11.9 µs |\n| Search top-10 | 12.0 µs |\n| Search top-50 | 12.1 µs |\n| Save to disk | 66 µs |\n| Load from disk | 57 µs |\n\n### TurboQuant MSE (dim=128)\n\n| Bit-width | Quantize | Dequantize |\n|---|---|---|\n| 1-bit | 3.9 µs | 991 ns |\n| 2-bit | 3.9 µs | 988 ns |\n| 3-bit | 3.9 µs | 997 ns |\n| 4-bit | 4.1 µs | 998 ns |\n\n### TurboQuant Prod (dim=128)\n\n| Bit-width | Quantize | Dequantize | IP Estimate |\n|---|---|---|---|\n| 2-bit | 116 µs | 141 µs | 111 µs |\n| 3-bit | 115 µs | 111 µs | 111 µs |\n| 4-bit | 115 µs | 111 µs | 112 µs |\n\n### Bit Packing\n\n| Operation | 128x2b | 384x2b | 384x4b |\n|---|---|---|---|\n| Pack | 161 ns | 539 ns | 264 ns |\n| Unpack | 90 ns | 270 ns | 241 ns |\n\n### Embedding Store\n\n| Operation | 128d x 100 | 384d x 100 | 384d x 500 |\n|---|---|---|---|\n| `upsert` | TBD | TBD | TBD |\n| `get` | TBD | TBD | TBD |\n| `remove` | TBD | TBD | TBD |\n| `save` | TBD | TBD | TBD |\n| `load` | TBD | TBD | TBD |\n\n### Inbox\n\n| Operation | cap=7 | cap=50 |\n|---|---|---|\n| `push_to_capacity` | TBD | TBD |\n| `push_with_eviction` | TBD | TBD |\n| `save` | TBD | TBD |\n| `load` | TBD | TBD |\n| `drain` | TBD | TBD |\n\n### Memory Index\n\n| Operation | 10 entries | 100 entries |\n|---|---|---|\n| `parse_line` | TBD | — |\n| `to_line` | TBD | — |\n| `search` | TBD | TBD |\n| `upsert_new` | TBD | TBD |\n| `upsert_existing` | TBD | TBD |\n\n### Eval Functions\n\n| Function | 32d x 50 | 128d x 50 | 384d x 20 |\n|---|---|---|---|\n| `anisotropy` | TBD | TBD | TBD |\n| `similarity_range` | TBD | TBD | TBD |\n| `mean_center` | TBD | TBD | TBD |\n| `discrimination_gap` | TBD | — | — |\n\n\u003e Measured on Apple Silicon (M-series) with `cargo bench`. Run `just bench` to reproduce.\n\u003e Raw results available in [`docs/benchmarks/`](benchmarks/).\n\u003c!-- /fsrc --\u003e\n\n## Testing\n\n```bash\njust test                  # cargo test --workspace\nbash scripts/validate.sh   # full E2E validation (requires release build)\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#testing) for what each test suite covers and per-crate test counts.\n\n## Agent Skill\n\nThis repo's conventions are available as portable agent skills in [`skills/`](skills/), following the [Agent Skills Specification](https://agentskills.io/specification).\n\nRelated standards: [AGENTS.md](https://agents.md/) · [llms.txt](https://llmstxt.org/)\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Fmnemonist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furmzd%2Fmnemonist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Fmnemonist/lists"}