Persistent Memory
A Markdown file the agent reads and writes to retain learnings, decisions, and project context across every session.
Overview
.misar/MEMORY.md is a plain Markdown file that persists what the agent learns about your project. It is automatically prepended to the system context at the start of every session — so the agent arrives informed, not blank.
Unlike MISAR.md (which holds static rules you write), MEMORY.md grows over time as the agent discovers facts worth remembering.
How It Works
Auto-load — at session start, the full contents of .misar/MEMORY.md are injected into the agent's system context before your first message.
Agent writes — when the agent learns something worth keeping (a quirk, a decision, a pattern), it calls the save_memory tool to append a new entry.
You edit — the file is plain Markdown. Open it, remove outdated entries, reorganise sections, or add facts manually at any time.
File Location
.misar/
└── MEMORY.md ← created automatically on first save_memory call
If the file does not exist, the agent creates it on the first save_memory call. You can also create it manually before that.
Format
MEMORY.md is free-form Markdown. A recommended structure:
# Project Memory
## Architecture Decisions
- Auth tokens are stored in httpOnly cookies, never localStorage (decided 2026-03-10)
- All DB access goes through `src/lib/db.ts` — never inline Supabase client calls
- Feature flags live in `src/lib/flags.ts`, not in environment variables
## Known Quirks
- The `useUserStore` hook re-renders on every route change — wrap consumers in `React.memo`
- `pnpm build` fails if `NEXT_PUBLIC_SITE_URL` is not set, even for local builds
- The staging environment does not have access to the payments service
## Preferred Patterns
- Use `zod` for all input validation; schemas live in `src/schemas/`
- Server Actions follow the naming pattern `<noun><Verb>Action` (e.g. `userUpdateAction`)
- Tests use `describe` blocks that mirror the module structure
## Team Preferences
- PRs need two approvals before merge
- Migration files must include a down migration
- Always run `pnpm typecheck` before opening a PR
Ask the agent to save something directly: "Remember that the payments service is only available in production." The agent will call save_memory and append it to the file.
What to Store
Architecture Decisions
Record why a pattern was chosen so future sessions understand the intent, not just the outcome.
Known Quirks
Document environment-specific gotchas, flaky tests, or non-obvious side effects the agent should avoid triggering.
Team Preferences
Capture review requirements, branch policies, or naming conventions agreed on by the team.
Discovered Context
Let the agent record what it learns during a session — file layouts, data shapes, API behaviour — so it does not re-discover them later.
Difference from MISAR.md
| | MISAR.md | MEMORY.md |
|-|----------|-----------|
| Author | You | Agent (and you) |
| Content | Static rules and conventions | Dynamic learnings and discoveries |
| Changes | Manual edits only | Grows via save_memory tool |
| Scope | Policy — what to do | Context — what is true |
Both files are loaded at session start and complement each other.
Keeping It Clean
MEMORY.md is not automatically pruned. Review it periodically and remove entries that are:
- No longer true (e.g. a quirk that was fixed)
- Superseded by a rule in MISAR.md
- Too granular to be useful across sessions
Commit .misar/MEMORY.md to your repository to share accumulated context with teammates. For personal preferences that should not be shared, use the global ~/.misar/MISAR.md instead.