{"id":49339397,"url":"https://github.com/fpsz/memori-vault","last_synced_at":"2026-04-27T03:02:57.735Z","repository":{"id":342609360,"uuid":"1174160378","full_name":"FPSZ/Memori-Vault","owner":"FPSZ","description":"Local-first memory engine for personal and team knowledge, combining semantic chunking, vector retrieval, and asynchronous Graph-RAG on Ollama + SQLite. 本地优先的个人与团队记忆引擎，集成语义分块、向量检索与异步 Graph-RAG（Ollama + SQLite）。","archived":false,"fork":false,"pushed_at":"2026-04-25T06:30:21.000Z","size":1952,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T08:33:56.269Z","etag":null,"topics":["enterprise-search","graph-rag","knowledge-base","local-first","ollama","rag","rust","semantic-search","sqlite","tauri"],"latest_commit_sha":null,"homepage":"","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/FPSZ.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":"CONTRIBUTING.en.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":null,"dco":null,"cla":null}},"created_at":"2026-03-06T06:08:50.000Z","updated_at":"2026-04-25T06:30:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FPSZ/Memori-Vault","commit_stats":null,"previous_names":["fpsz/memori-vault"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/FPSZ/Memori-Vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FPSZ%2FMemori-Vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FPSZ%2FMemori-Vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FPSZ%2FMemori-Vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FPSZ%2FMemori-Vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FPSZ","download_url":"https://codeload.github.com/FPSZ/Memori-Vault/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FPSZ%2FMemori-Vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32320686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"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":["enterprise-search","graph-rag","knowledge-base","local-first","ollama","rag","rust","semantic-search","sqlite","tauri"],"created_at":"2026-04-27T03:02:42.802Z","updated_at":"2026-04-27T03:02:57.728Z","avatar_url":"https://github.com/FPSZ.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memori-Vault\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-111111?style=flat-square)](./LICENSE)\n[![Rust 1.85+](https://img.shields.io/badge/Rust-1.85%2B-111111?style=flat-square\u0026logo=rust\u0026logoColor=white)](https://www.rust-lang.org)\n[![CI](https://img.shields.io/github/actions/workflow/status/FPSZ/Memori-Vault/rust-ci.yml?branch=main\u0026label=CI\u0026style=flat-square)](https://github.com/FPSZ/Memori-Vault/actions/workflows/rust-ci.yml)\n\n**Ask your documents. Know exactly where the answer came from.**\n\n[中文](./README.md) | [Contributing](./CONTRIBUTING.en.md) | [Tutorial](./docs/TUTORIAL.md) | [Memory OS Lite Architecture](./docs/MEMORY_OS_LITE.md)\n\n---\n\n## What Problem Does It Solve?\n\nKnowledge does not live in one chat window. It is scattered across Markdown files, TXT notes, PDFs, DOCX documents, code docs, project decisions, meeting notes, conversations, and agent tool calls. A typical RAG system can vectorize this content and return a plausible answer, but it often fails the questions that matter:\n\n- Which exact file and chunk supports this answer?\n- If evidence is weak, will the system refuse or hallucinate?\n- How do agent-generated memories get saved, updated, audited, and superseded without polluting document evidence?\n\nMemori-Vault is a **Local-first Verifiable Memory OS Lite**: a local, auditable memory engine that separates document evidence, conversation memory, project memory, graph context, model policy, and MCP agent access into explicit layers. It is designed to make a local knowledge base not only searchable, but trustworthy, traceable, and callable by agents.\n\nBy default, there is no cloud dependency, no mandatory external vector database, and no heavy SaaS stack. Core data stays in local SQLite, which makes Memori-Vault suitable for personal knowledge bases, engineering team knowledge bases, private deployment, and local agent memory.\n\n---\n\n## Why Not Other RAG Tools?\n\n| What You Care About | Typical RAG / Knowledge-Base Tooling | Memori-Vault |\n| --- | --- | --- |\n| Data location | Cloud service, remote vector DB, heavy service stack | Local SQLite file by default |\n| Offline use | Often depends on cloud models or hosted services | Works with local models and local indexes |\n| Answer trust | Usually shows a loose source list | Chunk-level citations, evidence, source groups, retrieval metrics |\n| Insufficient evidence | Often still generates a plausible answer | Strong-evidence gating and explicit insufficient-context status |\n| Chinese / CJK | Often treated as an afterthought | CJK, Traditional Chinese, mixed English/Chinese, code tokens, paths, and API names are core cases |\n| Long-term conversation memory | Often dumps chat logs into vector search | STM/MTM/LTM layers with source, lifecycle, and audit |\n| Agent integration | Custom HTTP wrappers or vendor-specific plugins | Official MCP for Claude Code, Codex, OpenCode, and local agents |\n| Graph | Missing or mixed into opaque ranking | Graph is evidence exploration and temporal relationship context, not main ranking |\n| Governance | SaaS permissions or heavy deployment | Local-first, egress policy, audit, RBAC/private deployment preview |\n| License | AGPL, proprietary, or commercial restrictions | Apache 2.0 |\n\nMemori-Vault is not trying to become an AnythingLLM clone. It focuses on a narrower and sharper product promise: **local, lightweight, trustworthy, verifiable, CJK-friendly, and agent-callable memory**.\n\n---\n\n## Core Strengths\n\n### 1. Verifiable Answers, Not Plausible Summaries\n\nStructured answers are built around an evidence chain:\n\n- `citations`: which files and chunks support the answer.\n- `evidence`: original matched snippets, hit reasons, and ranking signals.\n- `source_groups`: aggregation for duplicate or sibling sources, especially `.txt/.md` pairs.\n- `metrics`: retrieval, merge, and generation timings.\n- `failure_class`: recall miss, rank miss, gating false negative, generation refusal, or citation miss.\n\nThis makes the system explainable to users and debuggable for engineers. If there is not enough evidence, the correct behavior is to say so.\n\n### 2. Evidence Firewall\n\nLong-term memory is useful, but dangerous if it is mixed into document evidence. Preferences, project context, historical conversations, and agent summaries may help the answer, but they must not be disguised as file citations.\n\nMemori-Vault separates sources:\n\n- Document QA prioritizes document/chunk evidence.\n- Conversation, project, and preference memory is returned as `memory_context`.\n- `answer_source_mix` declares whether an answer is `document_only`, `document_plus_memory`, `memory_only`, or `insufficient`.\n- Document citations can only come from document chunks.\n\nThis is the Evidence Firewall: long-term memory can help context without weakening the evidence chain.\n\n### 3. Local-first Verifiable Memory OS Lite\n\nMemori-Vault is not just a vector store and not a strategy of stuffing everything into long context. It uses layered memory:\n\n| Layer | Stores | Purpose | Can It Be a Document Citation? |\n| --- | --- | --- | --- |\n| STM | Current session, active task, temporary tool results | Short-term working memory | No |\n| MTM | Session summaries, project context, recent decisions, failure records | Cross-session context | Only as memory source |\n| LTM | Document chunks, stable facts, durable preferences, project decisions | Long-term knowledge and preference | Document facts must be citeable |\n| TKG | Entities, relations, source chunks, time, conflicts | Graph explanation and timeline | Only sourced nodes and edges |\n| Policy | Egress policy, scope, agent write rules, model strategy | Governance boundary | No |\n\nImplemented or partially implemented today:\n\n- SQLite Memory Domain: `memory_events`, `memories`, `memory_lifecycle_log`.\n- Memory lifecycle operations: add, search, update, supersede, lifecycle log.\n- Ask-time Memory Router / Context Composer v1.\n- Trust Panel for answer source mix, failure class, token budget, source groups, and memory context.\n- Evidence compression so ordinary QA sends only the strongest evidence to the answer model.\n\nSee [docs/MEMORY_OS_LITE.md](./docs/MEMORY_OS_LITE.md) for the full architecture.\n\n### 4. SQLite Single-File Runtime\n\nThe default runtime keeps SQLite as the storage kernel:\n\n- Documents, chunks, FTS, vectors, graph metadata, memory, lifecycle logs, and audit data can stay local.\n- Backup, migration, and private deployment remain simple.\n- A local knowledge-base product does not need to become a Milvus/Chroma/Postgres/Docker cluster by default.\n- External vector adapters can be added later, but they should remain optional.\n\nThis makes Memori-Vault a good fit for desktop tools, local services, private networks, and personal/team agent memory.\n\n### 5. CJK and Mixed-Token Retrieval\n\nReal Chinese knowledge bases contain Simplified Chinese, Traditional Chinese, English abbreviations, paths, API names, code symbols, and business filler words. Memori-Vault treats these as first-class retrieval cases:\n\n- Chinese/CJK query analysis.\n- Traditional Chinese and Simplified Chinese content.\n- Mixed English/Chinese queries.\n- `snake_case`, `kebab-case`, `CamelCase`, paths, APIs, and function names.\n- Same-name files, duplicate document pairs, descriptive questions, and no-answer questions.\n\nThe near-term quality target is a fixed 50-case test set: answer at least 45, answer at least 40 correctly, and hit citations/source groups at least 45 times.\n\n### 6. Official MCP for Agents\n\nMemori-Vault exposes an official MCP server instead of only a custom HTTP endpoint. Agents can use the local vault through standard MCP tools.\n\nQuery and evidence:\n\n- `ask`\n- `search`\n- `get_source`\n- `open_source`\n\nMemory:\n\n- `memory_search`\n- `memory_add`\n- `memory_update`\n- `memory_list_recent`\n- `memory_get_source`\n\nIndexing, model settings, app settings, and graph tools are also exposed through MCP. Full-control mode can manage local runtime state, but long-term memory writes must carry source, audit, and a reversible lifecycle path.\n\n### 7. Graph for Explanation, Not Main Ranking\n\nGraph-RAG is valuable, but it should not become an opaque ranking dependency before the main evidence chain is stable. Memori-Vault uses graph as:\n\n- Evidence exploration.\n- Entity and relationship visualization.\n- Source chunk backtracking.\n- Temporal relationship and conflict explanation.\n- A non-blocking background layer.\n\nGraph extraction failure must not break ask/search, and graph score should not affect main ranking in the P1 architecture.\n\n---\n\n## Quick Start\n\n### Desktop Development\n\n```bash\ngit clone https://github.com/FPSZ/Memori-Vault.git\ncd Memori-Vault\n\npnpm --dir ui install\npnpm --dir ui run dev -- --host 127.0.0.1 --port 1420 --strictPort\ncargo tauri dev -p memori-desktop\n```\n\n### Server Only\n\n```bash\ncargo run -p memori-server\n```\n\nDefault server URL:\n\n```text\nhttp://127.0.0.1:3757\n```\n\nMCP HTTP endpoint:\n\n```text\nhttp://127.0.0.1:3757/mcp\n```\n\n### Local Model Roles\n\nMemori-Vault can use different local models for different jobs:\n\n```bash\nMEMORI_CHAT_ENDPOINT=http://localhost:8001   # main answer model, e.g. Qwen3 14B\nMEMORI_GRAPH_ENDPOINT=http://localhost:8002  # graph/summary/settings helper, e.g. Qwen3 8B\nMEMORI_EMBED_ENDPOINT=http://localhost:8003  # embedding model, e.g. Qwen3-Embedding-4B\n```\n\nDo not treat long context as the default memory strategy:\n\n- Ordinary QA: 8K-16K.\n- Multi-document synthesis: 16K-32K.\n- 64K: offline long-document summarization, batch processing, or map-reduce, not the default online ask path.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TD\n    Capture[Capture\u003cbr/\u003edocuments, conversations, MCP, tools, settings] --\u003e Normalize[Normalize\u003cbr/\u003echunk, event, fact, entity]\n    Normalize --\u003e Memory[Layered Memory\u003cbr/\u003eSTM, MTM, LTM, Graph, Policy]\n    Memory --\u003e Retrieve[Retrieval\u003cbr/\u003eFTS + dense + RRF + source grouping + rerank]\n    Retrieve --\u003e Compose[Context Composer\u003cbr/\u003ebudget, intent, Evidence Firewall]\n    Compose --\u003e Answer[Answer\u003cbr/\u003eanswer, citation, evidence, Trust Panel, MCP]\n    Answer --\u003e Lifecycle[Lifecycle\u003cbr/\u003eadd, update, supersede, noop, audit, export]\n    Lifecycle --\u003e Memory\n```\n\n### Module Map\n\n| Module | Responsibility |\n| --- | --- |\n| `memori-parser` | Parsing and semantic chunking for Markdown/TXT/PDF/DOCX and future formats |\n| `memori-storage` | SQLite schema, documents, chunks, FTS, graph, memory, lifecycle log |\n| `memori-core` | Query analysis, document routing, chunk retrieval, RRF/gating, Memory Router, Context Composer |\n| `memori-server` | Axum HTTP API, MCP endpoint, server runtime, private deployment entry |\n| `memori-desktop` | Tauri commands, desktop lifecycle, settings persistence, model runtime coordination |\n| `ui` | React UI, settings, Evidence/Trust Panel, source preview, graph and memory UI |\n| `deploy` | systemd, environment templates, backup/restore private deployment assets |\n\n### Ask Path\n\n```text\nanalyze query\n-\u003e document routing\n-\u003e memory context search\n-\u003e chunk retrieval\n-\u003e RRF merge and gating\n-\u003e context composer\n-\u003e answer synthesis\n-\u003e citation/evidence/source_groups/memory_context\n-\u003e Trust Panel / MCP response\n```\n\n### Retrieval Boundary\n\nThe main retrieval chain remains:\n\n```text\ndocument routing -\u003e chunk retrieval -\u003e RRF/gating -\u003e evidence/citation\n```\n\nGraph, conversation memory, and project memory are explanation/context layers by default. They should not rewrite main ranking until the evidence chain is stable enough.\n\n---\n\n## Current Status\n\nImplemented or partially implemented:\n\n- Desktop QA, citations, evidence, settings, and model configuration.\n- Server HTTP API and MCP endpoint.\n- SQLite document indexing, FTS/dense hybrid retrieval, RRF/gating.\n- Memory Domain v1 with memory tables, lifecycle log, and memory MCP tools.\n- Trust Panel and structured source fields.\n- Source grouping and evidence compression.\n- Enterprise private deployment preview with RBAC, audit, egress policy, and backup/restore templates.\n\nStill in progress:\n\n- 50-case acceptance set: `answered \u003e= 45/50`, `correct \u003e= 40/50`, `citation/source_group_hit \u003e= 45/50`.\n- PDF/DOCX/HTML ingestion hardening.\n- Lower gating false negatives, especially for `.txt`, Traditional Chinese, and duplicate document pairs.\n- Temporal graph explanation and graph visualization.\n- Markdown source-of-truth / export.\n- Memory heat score, conflict resolver, lifecycle classifier.\n- Continued large-file split for maintainability.\n\n---\n\n## Who Is It For?\n\n- Individuals who want a local document QA system without sending data to the cloud.\n- Engineering teams working with Chinese, Traditional Chinese, mixed English/Chinese, and code documentation.\n- Developers who want Claude Code, Codex, OpenCode, or local agents to use a local knowledge base and long-term memory.\n- Organizations that need private deployment, audit, model egress policy, and local governance.\n- Workflows where every answer must be traceable to evidence, not just fluent.\n\n---\n\n## What It Does Not Do\n\n- No default cloud sync.\n- No mandatory remote vector database.\n- No conversation memory disguised as document citations.\n- No graph ranking in the P1 main retrieval path.\n- No claim that 50k-document high-precision validation is already complete.\n- No assumption that long context replaces memory architecture.\n\n---\n\n## License\n\nApache License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffpsz%2Fmemori-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffpsz%2Fmemori-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffpsz%2Fmemori-vault/lists"}