Skip to content

README.en.md

Latest commit

 

History

History
175 lines (113 loc) · 9.41 KB

README.en.md

File metadata and controls

175 lines (113 loc) · 9.41 KB
Raw

Session Memory

中文说明

An AI agent memory tool for keeping high-value project context across sessions, without rereading long chat history.

What It Is

session-memory keeps the context that still affects future work, instead of storing full chat transcripts.

It mainly preserves:

  • current goal
  • working approach
  • key decisions
  • confirmed findings
  • failed paths
  • next step

What Problem It Solves

  • The session becomes too long and important context gets buried in chat noise
  • A new session has to reconstruct goals, constraints, and conclusions from scratch
  • The approach changed, but later it is hard to remember why
  • Branch research accumulates and starts polluting the main path

Quick Start

When used as a local agent skill, you can say:

session-memory save
session-memory restore
session-memory search <keyword>

For a first-time user, it is enough to know these three actions: restore context, save the main line, and search old conclusions.

These are agent prompts, not shell commands shipped by this repository. For direct command-line use, run the Python scripts under scripts/, for example:

python3 scripts/restore_session_memory.py --workspace "$PWD" --scope auto
python3 scripts/save_session_memory.py --workspace "$PWD" --scope auto --stage prepare
python3 scripts/search_session_memory.py --workspace "$PWD" --scope auto --query "keyword"

session-memory check is the agent's save gate. It answers whether the current state is worth saving, and usually does not need to be run manually. session-memory research-save is for side-path research that is worth keeping but should not overwrite the main line.

Saving should not keep piling the current chat into current.md. First classify the material: what still affects the next step stays in current.md; past-but-worth-tracing context goes to history.md; side-path research that has not joined the main line goes to research.md; tool noise is discarded.

When To Use

  • The current session is getting long and you are about to stop or switch to a new one
  • The main goal, approach, key conclusion, or next step has changed
  • You want to keep branch research without polluting the main line
  • You only want to check one old conclusion instead of restoring everything

What It Is Not For

  • Full documentation
  • Long-term knowledge base
  • Project management
  • Raw chat transcript backup

Design Philosophy

This tool comes from a lightweight way of working: record less noise, avoid heavy process, and keep only the context that changes how a project moves forward.

The core split is simple: current.md is the minimal current recovery snapshot, while history.md keeps past key changes that should not be lost. That keeps long gaps between saves from turning the current layer into another project history.

Hidden Maintenance Layer

This tool also includes lightweight sleep/dream and archive maintenance. They are hidden maintenance layers: they distill and slim memory when appropriate, but they are not primary user entry points and not a persistent background service.

dream-notes.md is overwritten on each distilled run, so it does not grow forever inside the project; the parts that do grow over time are the global dreams/ snapshot directory and the append-only history.md.

The default hot path only reads current.md, history.md, and dream-notes.md. archive is the cold layer created after dream-time slimming and should not be read unless archived context is explicitly requested.

For split research within the same project, the minimal research layer uses research.md as an append-only research log. research-save appends there instead of overwriting the main current.md. research.md participates in dream distillation and post-dream archive slimming, but it stays out of the default restore/search hot path unless research context is explicitly requested.

current.md now maintains a Last Updated field, and dream-notes.md also writes Last Updated. If either one is too old, treat it as a weak reference and verify the live project state before trusting it.

Memory Space Routing

By default, --scope auto tries to resolve the current directory into one shared project memory:

  • Git projects: use <git-root>/.session-memory/
  • Non-git projects: if an ancestor already has .session-memory/, reuse that shared layer
  • Only when no shared root exists does it fall back to the current directory's own .session-memory/

If one project needs multiple isolated research memories, create .session-memory/config.toml at the project root:

[spaces]
"current-path" = "current-research"
"legacy-path" = "legacy-research"

For convenience, top-level mappings such as "memory_a" = "current-research" are also accepted.

Rules:

  • each key is a memory space name and each value is a path relative to the project root
  • when the current working directory is inside one of those subdirectories, read/write operations switch to <subdir>/.session-memory/
  • if multiple configured paths overlap, the longest matching prefix wins
  • the shared project memory and routed spaces are not auto-merged or auto-read together
  • research-save still only appends to the matched space's research.md

Legacy Path Compatibility

Normal reads and writes now use agent-neutral paths only:

  • project level: <project>/.session-memory/
  • global level: ${SESSION_MEMORY_HOME:-$HOME/.session-memory}/

If old memory already exists, it is migrated into the new path before the command continues:

  • old project paths: <project>/.codex/session-memory/, <project>/.claude/session-memory/
  • old global paths: ${CODEX_HOME:-$HOME/.codex}/session-memory/, ${CLAUDE_HOME:-$HOME/.claude}/session-memory/

Migration moves the old directory contents into the new directory and removes the old session-memory directory. Empty project-level .codex/ or .claude/ parents are removed too; non-empty parents are left in place. Name conflicts never overwrite new files; old conflicting files are preserved under .session-memory/archive/legacy-imports/.

Common Commands

This section describes agent prompts. There are three primary user entry points:

  • session-memory 保存 / session-memory save
  • session-memory 恢复 / session-memory restore
  • session-memory 搜索 <关键词> / session-memory search <keyword>

Auxiliary entry points stay out of the main mental model:

  • session-memory 研究保存 / session-memory research-save: record side-path research without overwriting current.md
  • session-memory 检查 / session-memory check: let the agent decide whether saving is worthwhile; default output is only a save recommendation

Example Use Cases

  • After a session has accumulated enough research and decisions, use session-memory 保存 / session-memory save to keep the current context instead of re-explaining it later.
  • When continuing the same project in a new session, use session-memory 恢复 / session-memory restore to quickly recover the current goal, approach, and next step.
  • If you only need to check why a path was abandoned or whether something was already verified, use session-memory 搜索 <关键词> / session-memory search <keyword> for lightweight lookup.
  • If you are only recording staged findings inside the same memory space, use session-memory 研究保存 / session-memory research-save to append checkpoints into that space's research.md.
  • If the same project has two or more divergent research paths, define separate memory spaces in config.toml first, then run save / research-save / restore / search inside each routed path. That prevents local forks or sibling research directories from overwriting each other.

Core Files

  • current.md: minimal current recovery snapshot; where to continue now
  • current.md also keeps a Last Updated header
  • history.md: key changes, decisions, and old current-layer context that should not be lost
  • research.md: append-only research log for multiple work contexts in the same project
  • dream-notes.md: distilled heuristics, mistakes, and warning signals, with a Last Updated header
  • config.toml: optional project-level routing config for mapping subdirectories to isolated memory spaces

Archive

Archive is not a primary read layer or a daily user entry point. It is the cold-layer slimming step that follows a successful dream pass, storing superseded history, older dream snapshots, and research entries from research.md that were either merged into the main line or explicitly marked invalid.

python3 "<skill-root>/scripts/archive_session_memory.py" --workspace "$PWD" --scope auto --dry-run

archive should stay unread by default. Only include it when you explicitly want archived context, such as checking why an old branch was abandoned. The current search script's --include-archive option searches archive/history-archive.md and archive/research-archive.md in the current memory space.

Limitations

  • This tool depends on whether high-value information is consistently recorded. If current.md and history.md are not updated, restore quality will degrade.
  • It is designed for distilled project continuity, not as a replacement for full documentation, a knowledge base, or formal project management tools.
  • The sleep/dream flow is lightweight and does not guarantee perfect distilled output, so important conclusions still need human judgment.

Notes

This project is intended for local AI agent workflows.

License

MIT