aeterna-memory

v0.1.0

Published

13 days ago

Portable shared Markdown memory for any agent.

0High
0Medium
0Low

luome

Aeterna Memory

中文

Aeterna Memory 是一套面向多 agent 的共享记忆层。它把用户明确批准保存的长期记忆写入一个 agent 中立的 Markdown 目录，并提供 TypeScript / Node CLI 与 skill adapter，让 Codex、Claude Code、Cursor、OpenClaw、Pi、Hermes Agent 等不同运行时可以读取同一份记忆。

核心目标是可迁移性：记忆属于一个公共目录，例如 ~/.aeterna 或你指定的 AETERNA_HOME，可以复制、同步、备份、合并，也可以被多个 agent 同时使用。

Alpha Test

Aeterna Memory 目前处于 Alpha Test 阶段。核心文件布局、CLI 命令和 adapter 设计已经可试用，但命令细节、manifest 字段、adapter 路径和迁移策略仍可能调整。建议在真实长期使用前备份 AETERNA_HOME，并优先在个人或小范围 agent 工作流中验证。

特性

跨 agent 共享：所有支持 Aeterna 的 agent 只要指向同一个 AETERNA_HOME，就能读写同一份记忆。
Markdown 优先：长期记忆、临时 scratchpad、handoff、snapshot、policy、manifest 都是普通 Markdown 文件。
显式写入：只有用户明确要求记住或确认保存时，才写入 durable memory。
低 token 加载：load、snapshot、handoff 和 cadence 提供分层、省 token 的加载路径。
可迁移与可维护：支持 export、import、merge、manifest verify、sync status。
跨运行时 adapter：支持 Codex、Claude Code、Cursor、OpenClaw、Pi、Hermes Agent，以及 Open Skills repository layout。
本地安全工具：支持 secret scan、redaction、policy 管理。
Node 18/20 兼容：CLI 使用 TypeScript 构建，运行时目标为 Node.js >=18。

安装

安装 Aeterna skill：

npx skills add https://github.com/luome/Aeterna-Memory

使用 npx 直接运行：

npx -y aeterna-memory init

全局安装：

npm install -g aeterna-memory
aeterna init

本仓库开发模式：

npm install
npm run build
node dist/cli.js init

快速开始

以下操作通常由 Agent 帮你完成；这里列出命令只是为了帮助你理解 Aeterna CLI 的工作方式。

初始化共享记忆目录：

aeterna init

保存一条用户批准的长期记忆：

aeterna remember "用户偏好中文回答。" --scope user --tags language,style

以低 token 方式加载当前任务相关记忆：

aeterna load --profile startup --query "当前任务" --tokens 600

在高频 agent 会话中使用 cadence 控制加载频率：

aeterna cadence tick --event startup --query "当前任务" --tokens 600 --refresh-snapshot

切换 agent 或压缩上下文前写 handoff：

aeterna handoff write "当前已经完成 adapter 导出验证。" --next "继续完善 README"

记忆存放在哪里

默认目录：

~/.aeterna/

推荐为跨 agent、跨机器或私有同步设置共享目录：

export AETERNA_HOME=/shared/aeterna

典型目录结构：

~/.aeterna/
  MANIFEST.md
  MEMORY.md
  SCRATCHPAD.md
  HISTORY.md
  SNAPSHOT.md
  HANDOFF.md
  CADENCE.md
  SUMMARY.md
  INDEX.md
  POLICY.md
  daily/

文件职责：

| File | Purpose | | --- | --- | | MEMORY.md | 用户批准的长期记忆，核心事实源 | | SCRATCHPAD.md | 临时待办、短期工作项 | | daily/YYYY-MM-DD.md | 按日期追加的工作日志 | | HISTORY.md | 记忆修改审计记录 | | SNAPSHOT.md | 可复用的稳定启动上下文 | | HANDOFF.md | session / agent 切换时的交接信息 | | CADENCE.md | 多 agent 共享的加载频率与 turn 状态 | | SUMMARY.md / INDEX.md | 从长期记忆派生的低 token 视图 | | POLICY.md | 加载、安全、成本相关策略 | | MANIFEST.md | 可迁移性与能力清单 |

核心概念

Durable Memory

长期记忆只保存用户确认要保存的内容。每条记忆都有稳定 id、scope、tags、created、updated、source、status 等元数据。

aeterna remember "项目使用 TypeScript 和 Node 18。" --scope project --tags stack,node

常见 scope：

| Scope | Meaning | | --- | --- | | user | 用户偏好、长期习惯、表达风格 | | project | 当前项目约定、技术栈、决策 | | workflow | 可复用流程、检查步骤 | | agent | 某类 agent 的运行偏好 | | global | 所有上下文都适用的事实 | | general | 默认通用记忆 |

Progressive Loading

Aeterna 避免一次性把所有记忆加载进上下文。常用加载路径从轻到重：

| Path | Use case | | --- | --- | | snapshot read | 读取已生成的稳定上下文 | | cadence tick | 高频会话中按频率决定是否加载 | | load --profile startup | 新会话启动时的极简上下文 | | load --profile minimal | 手动请求的小上下文 | | load --profile project | 当前项目工作上下文 | | load --profile full | 审计、迁移、排查时的广泛上下文 |

Snapshot

Snapshot 是从 load 派生出的固定上下文，适合多个 agent 在同一阶段复用。

aeterna snapshot refresh --profile startup --query "current task" --tokens 600
aeterna snapshot read
aeterna snapshot status

Handoff

Handoff 用于 session 切换、agent 切换、上下文压缩前的交接。

aeterna handoff write "完成 TypeScript CLI cadence 实现。" \
  --next "验证 adapter 导出" \
  --blockers "无"

aeterna handoff read

Cadence

Cadence 是本地轻量版的频率与成本控制。它通过 CADENCE.md 在所有 agent 之间共享 turn 计数，控制记忆多久加载一次，以及每次默认注入多少 token。

aeterna cadence status
aeterna cadence set context-cadence 3
aeterna cadence set snapshot-cadence 5
aeterna cadence set context-tokens 600
aeterna cadence tick --event turn --query "current task"

默认策略位于 POLICY.md：

- context-cadence: 1
- snapshot-cadence: 5
- handoff-cadence: 0
- context-tokens: 600

命令总览

| Command | Purpose | | --- | --- | | init | 创建或修复共享记忆目录 | | where | 显示当前记忆路径 | | status | 显示记忆健康状态与数量 | | remember | 写入用户批准的长期记忆 | | recall | 读取长期记忆 | | search | 全文搜索记忆文件 | | review | 审阅近期或筛选后的长期记忆 | | edit | 修改指定记忆 | | forget | 删除指定记忆，并写入审计历史 | | deprecate | 将记忆标记为 deprecated | | promote | 将 scratch、daily 或文本提升为长期记忆 | | log | 管理 daily log | | scratch | 管理共享 scratchpad | | load | 构建省 token 的上下文 | | snapshot | 生成或读取稳定上下文 | | handoff | 生成或读取交接信息 | | cadence | 控制加载频率与 token 预算 | | context | 构建更宽的紧凑上下文 | | maintain | 去重并刷新派生视图 | | history | 查看记忆修改历史 | | conflicts | 检查疑似冲突或重叠记忆 | | export | 导出可迁移记忆目录或 zip | | import | 合并或替换导入记忆 | | merge | 合并另一个 Aeterna store | | manifest | 验证或重写 manifest | | sync | 检查同步准备状态 | | scan-secrets | 扫描可能的 secret | | redact | 对指定记忆做脱敏 | | policy | 管理本地 policy | | adapter | 导出或安装 agent adapter | | e2e | 模拟多 agent 共享记忆 |

Adapter

Aeterna 可以导出或安装不同 agent 运行时需要的 skill 文件。

npx skills add https://github.com/luome/Aeterna-Memory
aeterna adapter list
aeterna adapter paths
aeterna adapter export all --out ./dist-adapters
aeterna adapter install codex --scope global
aeterna adapter install cursor --scope project
aeterna adapter doctor all --scope project --shared-home /shared/aeterna

当前 adapter targets：

| Target | Project path | Global path | | --- | --- | --- | | skills | skills/aeterna | ~/.agents/skills/aeterna | | claude-code | .claude/skills/aeterna | ~/.claude/skills/aeterna | | cursor | .cursor/skills/aeterna | ~/.cursor/skills/aeterna | | codex | .agents/skills/aeterna | ~/.codex/skills/aeterna | | pi | .pi/skills/aeterna | ~/.pi/agent/skills/aeterna | | hermes-agent | .hermes/skills/aeterna | ~/.hermes/skills/aeterna | | openclaw | skills/aeterna | ~/.openclaw/skills/aeterna |

Pi adapter 还会导出 lifecycle extension，用于启动时注入 Aeterna context。

可迁移性

Aeterna 的迁移单位是整个 AETERNA_HOME 目录。

导出：

aeterna export ./aeterna-backup --format plain
aeterna export ./aeterna-backup.zip --format zip

导入：

aeterna import ./aeterna-backup --mode merge
aeterna import ./aeterna-backup --mode replace

合并另一个 store：

aeterna merge /path/to/another/aeterna

验证迁移准备状态：

aeterna manifest verify
aeterna sync status

跨 agent 验证：

aeterna e2e cross-agent --home /tmp/aeterna-e2e --query "cross-agent"

安全

在共享、导出或同步前，建议扫描 secret：

aeterna scan-secrets

脱敏指定记忆：

aeterna redact mem-...
aeterna redact mem-... --pattern "token=[^ ]+" --replacement "token=[REDACTED]"

Aeterna 不会自动判断哪些内容应该进入长期记忆。推荐原则：

只保存用户明确批准保存的内容。
不保存 API key、token、密码、私钥。
跨机器同步前先运行 scan-secrets。
对项目内部敏感信息使用私有同步或本地目录。

开发

npm install
npm run typecheck
npm run build
npm run check
npm pack --dry-run

项目结构：

.
  skills/
    aeterna/
      SKILL.md
      agents/
      references/
  src/
    cli.ts
  dist/
    cli.js
  package.json
  tsconfig.json

设计原则

记忆与 skill 解耦：skill 可以重新安装，记忆仍留在 AETERNA_HOME。
Markdown 可读可修复：没有私有数据库格式，普通文本工具即可审查。
共享目录即协议：不同 agent 通过相同文件布局协作。
低 token 默认路径：优先 snapshot、cadence、startup profile。
显式持久化：长期记忆写入需要用户意图。

License

MIT

English

Aeterna Memory is a shared memory layer for multiple AI agents. It stores user-approved durable memory in an agent-neutral Markdown directory and provides a TypeScript / Node CLI plus skill adapters so Codex, Claude Code, Cursor, OpenClaw, Pi, Hermes Agent, and other runtimes can read the same memory store.

The main goal is portability: memory lives in a public directory such as ~/.aeterna or your custom AETERNA_HOME. You can copy it, sync it, back it up, merge it, and point different agents at it.

Alpha Test

Aeterna Memory is currently in Alpha Test. The core file layout, CLI commands, and adapter design are usable, but command details, manifest fields, adapter paths, and migration behavior may still change. Back up AETERNA_HOME before relying on it for long-term use, and validate it first in a personal or small-scope agent workflow.

Features

Shared across agents: any supported agent can read and write the same memory when it uses the same AETERNA_HOME.
Markdown first: durable memory, scratchpad, handoff, snapshot, policy, and manifest are plain Markdown files.
Explicit writes: durable memory is written only when the user asks for it or confirms it should be saved.
Low-token loading: load, snapshot, handoff, and cadence provide layered context loading.
Portable and maintainable: includes export, import, merge, manifest verify, and sync status.
Cross-runtime adapters: supports Codex, Claude Code, Cursor, OpenClaw, Pi, Hermes Agent, and Open Skills repository layout.
Local safety tools: includes secret scanning, redaction, and policy management.
Node 18/20 compatible: the CLI is written in TypeScript and targets Node.js >=18.

Installation

Install the Aeterna skill:

npx skills add https://github.com/luome/Aeterna-Memory

Run with npx:

npx -y aeterna-memory init

Install globally:

npm install -g aeterna-memory
aeterna init

Local development:

npm install
npm run build
node dist/cli.js init

Quick Start

Agents usually run these commands for you; they are shown here only to help you understand how the Aeterna CLI works.

Initialize the shared memory directory:

aeterna init

Save a user-approved durable memory:

aeterna remember "The user prefers concise Chinese responses." --scope user --tags language,style

Load task-relevant memory with a small token budget:

aeterna load --profile startup --query "current task" --tokens 600

Use cadence for high-frequency agent sessions:

aeterna cadence tick --event startup --query "current task" --tokens 600 --refresh-snapshot

Write a handoff before switching agents or compacting context:

aeterna handoff write "Adapter export has been validated." --next "Continue improving README"

Where Memory Lives

Default directory:

~/.aeterna/

For cross-agent, cross-machine, or private sync use:

export AETERNA_HOME=/shared/aeterna

Typical layout:

~/.aeterna/
  MANIFEST.md
  MEMORY.md
  SCRATCHPAD.md
  HISTORY.md
  SNAPSHOT.md
  HANDOFF.md
  CADENCE.md
  SUMMARY.md
  INDEX.md
  POLICY.md
  daily/

File roles:

| File | Purpose | | --- | --- | | MEMORY.md | User-approved durable memory and primary fact source | | SCRATCHPAD.md | Temporary checklist and short-term work state | | daily/YYYY-MM-DD.md | Append-only dated work log | | HISTORY.md | Mutation audit log | | SNAPSHOT.md | Stable reusable startup context | | HANDOFF.md | Transfer notes for session or agent handoff | | CADENCE.md | Shared turn counters for cost-aware loading | | SUMMARY.md / INDEX.md | Derived low-token views | | POLICY.md | Loading, safety, and cost policy | | MANIFEST.md | Portability and capability manifest |

Core Concepts

Durable Memory

Durable memory stores only content the user approved. Every entry has stable metadata including id, scope, tags, created, updated, source, and status.

aeterna remember "The project uses TypeScript and Node 18." --scope project --tags stack,node

Common scopes:

| Scope | Meaning | | --- | --- | | user | User preferences and long-term habits | | project | Project conventions, stack, and decisions | | workflow | Reusable workflows and checklists | | agent | Agent-specific preferences | | global | Facts that apply everywhere | | general | Default general memory |

Progressive Loading

Aeterna avoids loading the whole store into context. Common paths, from lighter to broader:

| Path | Use case | | --- | --- | | snapshot read | Read an existing stable context | | cadence tick | Decide whether to load in high-frequency sessions | | load --profile startup | Very small new-session context | | load --profile minimal | Small manual context | | load --profile project | Active project context | | load --profile full | Broad context for audits, migration, or debugging |

Snapshot

A snapshot is a stable context derived from load, useful when several agents should reuse the same context during a work phase.

aeterna snapshot refresh --profile startup --query "current task" --tokens 600
aeterna snapshot read
aeterna snapshot status

Handoff

Handoff is for transferring work between sessions or agents.

aeterna handoff write "Finished TypeScript CLI cadence support." \
  --next "Validate adapter export" \
  --blockers "None"

aeterna handoff read

Cadence

Cadence is lightweight local frequency and cost control. It shares turn counters through CADENCE.md, so all agents using the same AETERNA_HOME follow the same loading rhythm.

aeterna cadence status
aeterna cadence set context-cadence 3
aeterna cadence set snapshot-cadence 5
aeterna cadence set context-tokens 600
aeterna cadence tick --event turn --query "current task"

Default policy in POLICY.md:

- context-cadence: 1
- snapshot-cadence: 5
- handoff-cadence: 0
- context-tokens: 600

Command Overview

| Command | Purpose | | --- | --- | | init | Create or repair the shared memory directory | | where | Show active memory paths | | status | Report memory health and inventory | | remember | Write user-approved durable memory | | recall | Read durable memory | | search | Full-text search memory files | | review | Review recent or filtered durable memories | | edit | Edit a memory entry | | forget | Delete a memory entry and log history | | deprecate | Mark memory as deprecated | | promote | Promote scratch, daily, or text to durable memory | | log | Manage daily logs | | scratch | Manage the shared scratchpad | | load | Build token-conscious context | | snapshot | Create or read stable context | | handoff | Create or read transfer notes | | cadence | Control load frequency and token budget | | context | Build broader compact context | | maintain | Deduplicate and refresh derived views | | history | Read mutation history | | conflicts | Detect likely contradictory or overlapping memory | | export | Export portable memory as plain directory or zip | | import | Import memory by merge or replace | | merge | Merge another Aeterna store | | manifest | Verify or rewrite the manifest | | sync | Check sync readiness | | scan-secrets | Scan for likely secrets | | redact | Redact a memory entry | | policy | Manage local policy | | adapter | Export or install agent adapters | | e2e | Simulate multiple agents sharing one memory store |

Adapters

Aeterna can export or install skill files for different agent runtimes.

npx skills add https://github.com/luome/Aeterna-Memory
aeterna adapter list
aeterna adapter paths
aeterna adapter export all --out ./dist-adapters
aeterna adapter install codex --scope global
aeterna adapter install cursor --scope project
aeterna adapter doctor all --scope project --shared-home /shared/aeterna

Current adapter targets:

The Pi adapter also exports a lifecycle extension for startup context injection.

Portability

The migration unit is the entire AETERNA_HOME directory.

Export:

aeterna export ./aeterna-backup --format plain
aeterna export ./aeterna-backup.zip --format zip

Import:

aeterna import ./aeterna-backup --mode merge
aeterna import ./aeterna-backup --mode replace

Merge another store:

aeterna merge /path/to/another/aeterna

Verify migration readiness:

aeterna manifest verify
aeterna sync status

Cross-agent verification:

aeterna e2e cross-agent --home /tmp/aeterna-e2e --query "cross-agent"

Safety

Before sharing, exporting, or syncing, scan for secrets:

aeterna scan-secrets

Redact a memory entry:

aeterna redact mem-...
aeterna redact mem-... --pattern "token=[^ ]+" --replacement "token=[REDACTED]"

Recommended rules:

Save only content the user approved.
Do not save API keys, tokens, passwords, or private keys.
Run scan-secrets before syncing across machines.
Use private sync or local-only storage for sensitive project memory.

Development

npm install
npm run typecheck
npm run build
npm run check
npm pack --dry-run

Project structure:

.
  skills/
    aeterna/
      SKILL.md
      agents/
      references/
  src/
    cli.ts
  dist/
    cli.js
  package.json
  tsconfig.json

Design Principles

Memory is decoupled from the skill: reinstalling the skill does not move or erase AETERNA_HOME.
Markdown is readable and repairable: no private database format is required.
The shared directory is the protocol: agents collaborate through the same file layout.
Low-token path by default: prefer snapshot, cadence, and startup profiles.
Explicit persistence: durable memory writes require user intent.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Aeterna Memory

中文

Alpha Test

特性

安装

快速开始

记忆存放在哪里

核心概念

Durable Memory

Progressive Loading

Snapshot

Handoff

Cadence

命令总览

Adapter

可迁移性

安全

开发

设计原则

License

English

Alpha Test

Features

Installation

Quick Start

Where Memory Lives

Core Concepts

Durable Memory

Progressive Loading

Snapshot

Handoff

Cadence

Command Overview

Adapters

Portability

Safety

Development

Design Principles

License