hippocampus-mcp 0.1.0__tar.gz

hippocampus_mcp-0.1.0/.gitignore

@@ -0,0 +1,172 @@
+# ==================================================================
+# HippoMCP .gitignore
+# 原则：**源码进库，数据不进库**。
+# 本仓库是研究型项目，工作目录里混有私人语料、模型缓存与实验产物，
+# 这些都必须在 push 前挡在门外。
+# ==================================================================
+
+# ------------------------------------------------------------------
+# P0 · 本地数据与训练产物不进库
+# ------------------------------------------------------------------
+# data/ 内含真实记忆库、备份快照、评测数据集与训练权重，一旦推上去无法撤回。
+data/
+
+# 个人知识系统与工作日志
+# （另有私人目录字面名在本机 .git/info/exclude——字面名不得进公开面）
+.workbuddy/
+
+# 内部流程记录与特定宿主接入单，脱敏后再公开
+docs/integration/
+docs/guides/ZCode恢复使用操作单.md
+docs/guides/ZCode操作说明.md
+docs/guides/ZCode接入指南.md
+
+# ------------------------------------------------------------------
+# P0 · 密钥（即使已改用环境变量，也防手滑留下 .env）
+# ------------------------------------------------------------------
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+secrets.json
+credentials.json
+
+# ------------------------------------------------------------------
+# 依赖缓存：175M 的内置包（py3.10 编译的老包，不该进版本库）
+# ------------------------------------------------------------------
+libs/
+*.whl
+.venv/
+venv/
+env/
+
+# ------------------------------------------------------------------
+# 实验产物与代码快照
+# ------------------------------------------------------------------
+# 各版本评测结果（脚本按字面路径写入，本地保留以便复现）
+eval_v*/
+eval_t1_attribution/
+
+# 源码/脚本快照目录（本地做 A/B 对照用，不进库）
+*_snap_*/
+
+# 脱敏前的本地快照（回滚用）与公开层导出测试目录
+snap_prekeys_*/
+_public_test/
+
+# 改动前的本地快照（如 docs/TODO.md.bak-2026xxxx）。**故意不进库**：
+# 一是快照会跟正文一起漂移、污染 diff；二是 TODO 快照里同样含真实库名/项目名，
+# 而公开层白名单只认 docs/TODO.md 本体，快照漏进来就是绕过白名单。
+# 2026-09-22 加：上一轮用的 `git add -A` 会把这类文件一并扫进暂存区。
+*.bak
+*.bak-*
+*.bak_*
+
+# 评测报告产物
+hippocampus-evaluation-report/
+mem0-comparison/
+phase5-evaluation-report/
+*_report.html
+*_report_st.html
+evaluation-painpoint-analysis.html
+research-retrospective.html
+
+# ------------------------------------------------------------------
+# 实验残留：根目录散落的临时脚本与输出
+# ------------------------------------------------------------------
+# 一次性脚本（已被 scripts/ 下的版本取代）
+/run_eval.py
+/run_eval_st.py
+/run_locomo_eval.py
+/run_pro_eval.py
+/test_minimal_loop.py
+/_probe_loopback_mcp.py
+/train_cfc.py
+/train_cfc_retrieval.py
+/migrate_package.py
+/migrate_package.ps1
+/README_TEST.txt
+
+# 一次性输出
+/*.log
+/*_test.txt
+/permission_test_v2.txt
+/sandbox_test.txt
+/visibility_test.txt
+/win32_direct_test.txt
+/real_write_test.txt
+/perf_after_fix.log
+/perf_baseline_before_fix.log
+
+# 根目录散落的评测结果 JSON（正式结果统一放 eval_vXX/）
+/crl_eval_results.json
+/eval_results.json
+/eval_results_st.json
+/llm_eval_results.json
+/locomo_eval_results.json
+/p7_corrected_metrics.json
+/pro_eval_results.json
+
+# ------------------------------------------------------------------
+# 模型权重与二进制
+# ------------------------------------------------------------------
+*.pt
+*.pth
+*.onnx
+*.npz
+*.bin
+*.safetensors
+!docs/**/*.json
+
+# ------------------------------------------------------------------
+# 调试现场
+# ------------------------------------------------------------------
+_probe_out/
+mcp_server_debug.log
+# 改动前的版本快照（`_backup/<日期>_<主题>/<原路径>`）。是回滚用的本机副本，
+# 不是交付物：进库只会让 diff 里混进整份旧文件。
+_backup/
+
+# GitHub 建仓（B1-4）一次性注册现场：含浏览器自动化脚本、截图、cookies.txt、
+# hosts 文件，71MB，**绝不可进库**（cookies 属凭据）。注册完即弃。
+_gh_signup/
+
+# ------------------------------------------------------------------
+# Python
+# ------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# ------------------------------------------------------------------
+# 编辑器与系统
+# ------------------------------------------------------------------
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ------------------------------------------------------------------
+# 本机宿主/引导配置（2026-10-16）
+#   .hippocampus.json 优先级高于 HIPPOCAMPUS_PERSIST_DIR，且含本机绝对路径。
+#   从仓库根跑测试时它会把「自行指定库目录」的用例静默重定向到引导库，
+#   实测造成 4 个套件假失败（10-16）。这类文件绝不进仓。
+# ------------------------------------------------------------------
+.hippocampus.json
+.mcp.json
+.zcode/

hippocampus_mcp-0.1.0/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "HippoMCP: A Long-Term Memory Layer for LLM Hosts via MCP"
+abstract: >-
+  A service that provides long-term memory to LLM hosts through MCP
+  (Model Context Protocol). Unlike "adding a vector store to an app",
+  it covers the full path from writing, retrieval, and curation to
+  hand-assembled context slots: a four-layer memory model (raw stream /
+  facts / summaries / profile), cascade deletion with tombstones,
+  a superseded state machine (old facts are marked superseded, not erased),
+  CfC-based temporal encoding inspired by liquid neural networks,
+  and 5-slot context assembly with an independent token budget.
+authors:
+  - name: "cstksniper"
+    email: "cstksniper@qq.com"
+version: 0.1.0
+date-released: "2026-09-20"
+license: MIT
+repository-code: "https://github.com/cstksniper/hippocampus-mcp"
+keywords:
+  - memory
+  - MCP
+  - model-context-protocol
+  - LLM agent
+  - retrieval
+  - temporal-reasoning
+  - liquid-neural-network
+  - knowledge-management

hippocampus_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Code of Conduct
+
+## Our pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible
+or invisible disability, ethnicity, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Behavior that contributes to a positive environment includes:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Unacceptable behavior includes:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information (such as an address or email) without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our responsibilities
+
+Maintainers are responsible for clarifying the standards of acceptable behavior
+and are expected to take appropriate and fair corrective action in response to
+any instances of unacceptable behavior, including removal, editing, or rejection
+of comments, commits, code, issues, and other contributions that do not align
+with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (repository, issues,
+pull requests, discussions), and also applies when an individual officially
+represents the project or its community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported through an issue; for anything private or unsuitable for public
+discussion, email [cstksniper@qq.com](mailto:cstksniper@qq.com) directly.
+All complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances. The project team
+is obligated to maintain confidentiality with regard to the reporter of an incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

hippocampus_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,140 @@
+# Contributing
+
+Thank you for spending time on this project. This document explains **how to get
+changes in safely**, plus a few hard constraints — most of them come from real
+incidents, not style preferences.
+
+---
+
+## Development environment
+
+```bash
+git clone <your fork>
+cd hippocampus-mcp
+
+# Base dependencies
+pip install -e .
+
+# Full development chain (including NER / evaluation)
+pip install -e ".[dev,ner]"
+```
+
+Python **>= 3.11** is required (verified baseline; 3.10 is untested and unsupported).
+
+**Quick smoke run** (downloads no models):
+
+```bash
+PYTHONPATH=src python examples/quickstart.py
+```
+
+It uses `embedder_backend="hash"` — no sentence-transformers, no API key.
+
+---
+
+## Read before coding: five hard constraints
+
+These are not suggestions. PRs that violate them get bounced — not for style,
+but because they **cause silent errors**.
+
+### 1. The embedding model has exactly one source of truth
+
+Model-name resolution happens only in `embeddings.resolve_embedder_model()`,
+with priority **argument > env > default**. Do not copy env literals elsewhere.
+
+Reason: multiple entry points used to read the env independently; one forgot to
+set it and a Chinese library silently ran on the English model, with no error
+anywhere. `brain_stats()["embedder_model_source"]` now self-reports the source —
+keep it valid when touching related code.
+
+### 2. The only legal entry point for switching embedding models is `scripts/reembed.py`
+
+Changing the model via raw config makes stored vectors mismatch the new model.
+`MemoryManager._sync_embedder_with_store()` handles it:
+explicitly specified but mismatched → error; default but mismatched → **follow the model already in the library**.
+
+### 3. Deletion must cascade
+
+L2 / L3 / index layers are derived copies of L1 — **deleting L1 alone is a fake
+deletion**. The only entry point is `brain.forget(id, reason)`, which runs a
+6-step cascade internally.
+
+### 4. Filtering must happen before retrieval
+
+Structured tag filtering must use `search(allow_ids=)`, masking out-of-whitelist
+entries with `-inf`. **The BM25 path must filter explicitly**, otherwise the
+filter is bypassed.
+
+### 5. Every MCP tool must pass `structured_output=False`
+
+All of them, no exceptions — otherwise the host receives duplicated returns.
+
+More engineering conventions: the "engineering constraints" section of
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+---
+
+## Testing
+
+```bash
+# Run all public suites (~16 min, ~155 suites / 4700+ assertions)
+python scripts/run_all_tests.py
+
+# Only suites whose name contains "forget"
+python scripts/run_all_tests.py -k forget
+
+# Also run private suites under scripts/
+python scripts/run_all_tests.py --include-scripts
+```
+
+`scripts/run_all_tests.py` **uses only the standard library**; pytest is not
+required. If pytest is installed, `pytest tests/` works too (`pytest.ini` is
+configured).
+
+**Bar for new tests**: discoverable by `run_all_tests.py`, no private data, no
+real model downloads, no absolute paths written into the repo. Only tests
+meeting all four go into `tests/`; everything else goes to `scripts/`
+(the private layer).
+
+---
+
+## Commits and PRs
+
+- Commit messages in **Chinese or English**, but they must say **why**, not just what
+- One PR does one thing; keep refactors and feature changes separate
+- `src/` changes must attach test results (which suites were run)
+- Evaluation changes must state whether the numbers moved
+
+---
+
+## ⚠️ Public / private boundary
+
+This repository is exported from a research repository containing private data,
+and **the boundary is hard**:
+
+| Layer | Content | Rule |
+|---|---|---|
+| Public layer | whitelisted `src/`, `tests/`, `examples/`, `docs/` | free to change |
+| Private layer | `data/`, `.env`, personal corpora | **never commit**; mounted via `HIPPOCAMPUS_PERSIST_DIR` |
+| Process layer | `eval_v*/`, `*_snap_*/`, `_probe_out/` | already in `.gitignore`, never enters the repo |
+
+**Self-check before committing**:
+
+```bash
+python tools/export_public.py --audit
+```
+
+It scans the whole repository and reports hits for secrets, private data, and
+absolute paths. Files that hit sensitive content are **refused at export time**
+instead of being silently copied.
+
+---
+
+## Reporting issues
+
+Use the templates in `.github/ISSUE_TEMPLATE/`. When reporting a bug, attach the
+output of `brain_stats()` — its self-report fields (NER backend, embedding model
+source, L0 dangling count, tag coverage) usually pinpoint the problem directly.
+
+For security issues, private-data exposure, and anything unsuitable for public
+discussion, email [cstksniper@qq.com](mailto:cstksniper@qq.com) directly instead
+of opening an issue first.

hippocampus_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cstksniper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.