mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-10-26 18:55:22 +00:00
云服务部-叶林立
312bb2ba5a
从官方 Git 仓库导入 chandra447/pi-hermes-memory 在 tag v0.9.10 （df624056a2e8c68bc89ba0a81e1c120856ec9665，2026-10-02）的源码快照。 本次仅导入源码，尚未接入组合包：package.json、加载顺序、依赖与权限策略 均未改动。 - 原样导入 src/、tests/、docs/、scripts/、README、CHANGELOG、PLAN、 AGENTS 与 LICENSE；该快照共 156 个上游文件。 - 剔除嵌套 .git、上游 .github 工作流、.ralph/、.claude/、node_modules、 覆盖率与构建产物。 - 新增中文 UPSTREAM.md，记录来源，以及启用前必须完成的待决事项： 在 pi-compaction 之前注册加载顺序、better-sqlite3 版本与根 allowScripts 对齐、strip-ansi 解析确认。 - 说明选择 tag 而非 main 的原因：导入时上游 main 已领先至 24fcd8ad26fc27badb8d7dbaf8034645de07b893（2026-10-11），选 tag 是为 对应一个已发布、可复现的版本。 尚未接线。启用前还需反转 tests/extension-load.test.ts 中"不得加载 Hermes"的断言，并同步 pi-tool-search 分组、权限策略与文档。 验证：快照 156 个上游文件全部导入，目录内仅多出 UPSTREAM.md 一份； 已确认与上游 main 内容存在差异，证明取的是 tag 而非 main。
78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
# Pi Hermes Memory Extension
|
|
|
|
## Project Overview
|
|
|
|
This is a Pi coding agent extension that brings Hermes-style persistent memory and a learning loop to any Pi user. After `pi install`, users get persistent memory across sessions, a background learning loop, and session-end flush.
|
|
|
|
**v0.1 is complete** (119 tests, v0.1.0 tagged). Current work is **v0.2: Skills + Smart Curation** — see `docs/0.2/TASKS.md`.
|
|
|
|
## Architecture
|
|
|
|
- **Language**: TypeScript (loaded via jiti, no compilation needed at runtime)
|
|
- **Runtime**: Pi extension API (`@earendil-works/pi-coding-agent`)
|
|
- **Storage**: Two markdown files (`MEMORY.md`, `USER.md`) in `~/.pi/agent/memory/`
|
|
- **Entry point**: `src/index.ts` — registers tools, event handlers, and commands
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|---|---
|
|
| `src/index.ts` | Extension entry point — wires all components together |
|
|
| `src/types.ts` | Shared TypeScript interfaces + `getMessageText()` helper |
|
|
| `src/constants.ts` | Prompts, defaults, delimiter |
|
|
| `src/store/memory-store.ts` | Core `MemoryStore` class — CRUD, persistence, frozen snapshot |
|
|
| `src/store/content-scanner.ts` | `scanContent()` — injection/exfiltration detection |
|
|
| `src/tools/memory-tool.ts` | `registerMemoryTool()` — LLM tool definition |
|
|
| `src/handlers/background-review.ts` | `setupBackgroundReview()` — learning loop via `pi.exec` |
|
|
| `src/handlers/session-flush.ts` | `setupSessionFlush()` — pre-compaction/shutdown flush |
|
|
| `src/handlers/insights.ts` | `registerInsightsCommand()` — `/memory-insights` command |
|
|
| `PLAN.md` | Full v0.1 implementation plan with Hermes source file reference map |
|
|
| `docs/ROADMAP.md` | Full roadmap with Hermes competitive analysis + gap analysis |
|
|
| `docs/0.2/TASKS.md` | v0.2 task breakdown — Skills + Smart Curation |
|
|
|
|
## Design Decisions
|
|
|
|
1. **Frozen snapshot** — Memory is injected into system prompt once at session start, never mutated mid-session (preserves Pi's prompt caching)
|
|
2. **Atomic writes** — Temp file + `fs.rename()` for crash safety
|
|
3. **`pi.exec()` for background review** — Stays within Pi's intended extension API
|
|
4. **`§` delimiter** — Same as Hermes for consistency
|
|
5. **No SQLite** — Pi has its own `SessionManager`, we read from it directly
|
|
|
|
## Hermes Source Reference
|
|
|
|
The implementation is ported from the Hermes agent harness. See `PLAN.md` → "Hermes Source File Reference Map" for exact files and line ranges to read.
|
|
|
|
## Roadmap & Task Tracking
|
|
|
|
- **Roadmap**: `docs/ROADMAP.md` — full roadmap with Hermes competitive analysis, gap analysis, and phased plan (v0.1 → v0.5 → v1.0)
|
|
- **v0.1 tasks** (complete): `docs/0.1/TASKS.md`
|
|
- **v0.2 tasks** (current): `docs/0.2/TASKS.md` — Skills, auto-consolidation, correction detection, tool-call-aware nudge
|
|
|
|
**Workflow:**
|
|
1. Pick a task from `docs/0.2/TASKS.md`
|
|
2. Mark it `[~]` (in progress)
|
|
3. Implement it
|
|
4. Mark it `[x]` (done) with the commit hash
|
|
5. Move to the next task
|
|
|
|
**Before starting any work, read `docs/0.2/TASKS.md` to see what's next.**
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Type check
|
|
npm run check
|
|
|
|
# Test locally
|
|
pi -e ./src/index.ts
|
|
```
|
|
|
|
## Installation (for users)
|
|
|
|
```bash
|
|
pi install npm:pi-hermes-memory
|
|
|
|
# or from git
|
|
pi install git:github.com/chandra447/pi-hermes-memory
|
|
```
|