English | 中文
A dual-store memory architecture for AI assistants: authoritative Git Markdown + optional experience memory (TDAI).
AI-Memory manages "what is true right now." Experience memory helps recall "what happened before." Confirm the present, then consult the past.
git clone https://github.com/hczxy05/ai-memory-framework.git ~/ai-memory- Fill in
personal/universal-memory.mdwith stable user info and preferences. - Add your projects to
project/projects.md; adjustrules/conventions.mdas needed. - Tell your Agent to read
~/ai-memory/AGENTS.mdat the start of every task.
That's it — Git Markdown memory works standalone. TDAI experience memory is an optional enhancement.
AI assistants lose context between sessions. Worse, they can mistake stale conversations for current facts. This framework separates two fundamentally different kinds of information:
- Authoritative memory — confirmed rules, facts, status, architecture, and decisions. Human-readable, Git-tracked.
- Experience memory — conversations, attempts, extracted lessons, and profiles. For historical reference only; may be outdated or wrong.
Both stores collaborate, but they are not equal.
Incoming user instruction
↓
Agent Rules: AGENTS.md · memory-policy.md · authority.md · conventions.md · memory-promotion.md
↓
Personal Memory: user info · preferences · background
↓
Project Memory: project status · architecture · decisions · bugs · lessons
↓
Experience Memory (optional): conversations · attempts · scenarios · profiles
Priority: current instruction > agent rules > project memory > personal memory > experience > raw history
| Layer | Location | Purpose |
|---|---|---|
| Agent Rules | rules/ |
How agents behave: authority, policy, promotion, conventions |
| Personal Memory | personal/ |
About the user: info, preferences, background |
| Project Memory | project/ + per-project docs |
About the project: status, architecture, decisions, bugs |
| Experience Memory | Optional TDAI provider | Historical evidence: conversations, attempts, candidates |
When multiple agents produce conflicting information, the authority system determines what to trust:
| Level | Source | Rule |
|---|---|---|
| 0 | User Instruction | Highest — overrides everything |
| 1 | Agent Rules (rules/) |
Governance, safety |
| 2 | Project Memory | Current verified truth |
| 3 | Personal Memory | User preferences |
| 4 | Verified Experience (TDAI, test results) | Evidence only, verify first |
| 5 | Agent Memory (ChatGPT/Codex/Claude) | Hints, not decisions |
| 6 | Raw History | Lowest priority |
Conflicts are reported, not silently resolved. See rules/authority.md for full rules.
Experience cannot directly write to authoritative memory. Information must pass through a lifecycle:
Observation → Experience → Candidate → Verified → Authoritative
Promotion requires all five: Stable, Reusable, Verified, Relevant, Authorized.
Example (STM32 PWM bug):
| Stage | Content |
|---|---|
| Observation | "TIM2 has no PWM output after restart" |
| Experience | "Suspect HAL_TIM_PWM_Stop causes the issue" |
| Candidate | "Stop clears CCER register, restart doesn't restore it" |
| Verified | "Modified to use CCER control — PWM works correctly" |
| Authoritative | Written to BUGS.md as confirmed root cause |
See rules/memory-promotion.md for full rules.
ai-memory-framework/
├── AGENTS.md # Behaviour summary loaded at every task
├── personal/ # Personal Memory (about the user)
│ └── universal-memory.md # User info, preferences, background
├── project/ # Project Memory (about projects)
│ └── projects.md # Project index and navigation
├── rules/ # Agent Rules (how agents behave)
│ ├── authority.md # Authority level definitions (P0-P5)
│ ├── memory-policy.md # Full memory specification
│ ├── memory-promotion.md # Memory states and promotion lifecycle
│ ├── conventions.md # Stable collaboration conventions
│ └── changelog.md # Version change log
├── templates/
│ ├── project-template.md
│ ├── task-template.md
│ └── report-template.md
├── integrations/
│ ├── openclaw-tdai-local/
│ └── codex-tdai-local/
├── workspace-example/ # OpenClaw workspace example
│ ├── AGENTS.md
│ ├── IDENTITY.md
│ ├── SOUL.md
│ ├── USER.md
│ ├── TOOLS.md
│ ├── MEMORY.md
│ └── memory-manual.md # One-page quick reference
└── examples/tdai/ # Provider-generated content examples
├── persona.md
├── .metadata/experience_contract.json
└── scene_blocks/example-scene.md
Load AGENTS.md
→ Read only the authoritative memory needed for this task
→ Optionally run one round of experience retrieval (1 search tool, max 3 results)
→ Show each item with source, date, scope, and conflict notes
→ Let the user decide whether to continue
→ Distinguish confirmed facts, historical evidence, inferences, and unknowns
Candidate content → validate → propose specific changes and target file → user authorizes → write to authoritative memory
Experience memory cannot directly modify governance or authoritative files.
No experience memory provider available? Just keep using Git Markdown — it works fine on its own.
Add this bootstrap rule to your workspace AGENTS.md:
Read <ai-memory-path>/AGENTS.md at the start of every task, and follow its loading, retrieval, and writing rules.OpenClaw users can copy workspace-example/ and fill in identity, user, and tool details. USER.md and MEMORY.md are workspace context only; stable facts still live in the AI-Memory file responsible for that information.
| Principle | Meaning |
|---|---|
| Minimal context | Load only what the task needs |
| Layered authority | Historical evidence cannot override current facts |
| Controlled writes | Long-term memory must be confirmed, stable, reusable, and user-authorized |
| Honest uncertainty | Clearly distinguish facts, inferences, and unknowns |
| Human control | High-risk, destructive, or external actions require confirmation first |
- Use
templates/project-template.mdto create aSTATUS.mdor modularPROJECT.mdin your project repo. - For larger projects, add
ARCHITECTURE.md,DECISIONS.md,BUGS.md,LESSONS.mdas needed. - Register the project path in
project/projects.md.
- OpenClaw — supports local TDAI integration.
- Codex — access experience memory via local MCP adapter.
- Other AI assistants — any tool that reads Markdown can use the authoritative memory layer.
- Never store passwords, API keys, tokens, or private keys in memory.
- Never commit runtime databases, raw conversations, or full tool configurations to this repo.
- Deployment, destructive operations, financial actions, and physical control require explicit authorization first.
Built through iterative human-AI collaboration across real engineering workflows.