Neural Memory
Persistent memory for AI agents — stores experiences as interconnected neurons, recalls through spreading activation.
Session Lifecycle
- Start:
nmem_recap() → nmem_recall("<project> <topic>")
- During:
nmem_remember(...) after each completed task
- End:
nmem_auto(action="process", text="brief summary")
- Emergency:
nmem_auto(action="flush", text="...") before /compact
Save — When & How
nmem_remember(content="Chose X over Y because Z", type="decision", priority=7, tags=["project", "topic"])
| Signal |
type |
priority |
| Chose between alternatives |
decision |
7 |
| Fixed a bug (root cause + fix) |
error |
7 |
| Discovered a pattern |
insight |
6 |
| Learned user preference |
preference |
8 |
| Established a process |
workflow |
6 |
| Reusable fact |
fact |
5 |
| User instruction |
instruction |
8 |
Quality (system scores 0-10 automatically):
- Causal language: "X because Y", "chose X over Y", "root cause was X"
- Include specifics: file paths, versions, error traces
- 50-300 chars optimal. >500 chars penalized — split instead.
- Scratch notes:
ephemeral=true (24h, never synced)
- Do NOT save: routine file reads, things in git, duplicates
Recall
nmem_recall(query="project auth bug") # depth auto-detected
- Causal queries ("why", "because", "caused") activate cause-effect chains
- Fixes auto-supersede errors (old errors demoted when fix is stored)
- Prefix queries with project name for accuracy
Smart Behaviors (automatic)
- Quality scoring: specificity, structure, brevity scored per memory
- Dedup: similar memories flagged — use nmem_edit instead of duplicating
- Causal synapses: fixes create RESOLVED_BY links, demote old errors
- Stale detection: old-version references get -20% retrieval penalty
- Cold demotion: 0 access in 30d → cold; 90d → prune candidate (pinned exempt)
- SimHash merge: content-similar memories consolidated; 5+ group → summary fiber
Key Tools
| Tool |
When |
nmem_recall |
Query memories (depth auto-detected) |
nmem_context |
Load recent memories at session start |
nmem_recap |
Resume session (level=1-3, topic="X") |
nmem_session |
Track session state (get/set/end) |
nmem_edit |
Fix wrong type/content/priority |
nmem_forget |
Remove outdated memories (soft/hard) |
nmem_index |
Scan codebase into memory graph |
nmem_train |
Train docs into permanent knowledge |
nmem_health |
Brain grade + top penalties to fix |
nmem_explain |
Trace path between two concepts |
nmem_cognitive |
Hypotheses + predictions dashboard |
All tools: compact=true saves 60-80% tokens.
Links
1---2name: claude-plugin3description: Neural Memory4---5# Neural Memory67Persistent memory for AI agents — stores experiences as interconnected neurons, recalls through spreading activation.89## Session Lifecycle10111. **Start**: `nmem_recap()` → `nmem_recall("<project> <topic>")`122. **During**: `nmem_remember(...)` after each completed task133. **End**: `nmem_auto(action="process", text="brief summary")`144. **Emergency**: `nmem_auto(action="flush", text="...")` before /compact1516## Save — When & How1718```19nmem_remember(content="Chose X over Y because Z", type="decision", priority=7, tags=["project", "topic"])20```2122| Signal | type | priority |23|--------|------|----------|24| Chose between alternatives | decision | 7 |25| Fixed a bug (root cause + fix) | error | 7 |26| Discovered a pattern | insight | 6 |27| Learned user preference | preference | 8 |28| Established a process | workflow | 6 |29| Reusable fact | fact | 5 |30| User instruction | instruction | 8 |3132**Quality** (system scores 0-10 automatically):33- Causal language: "X because Y", "chose X over Y", "root cause was X"34- Include specifics: file paths, versions, error traces35- 50-300 chars optimal. >500 chars penalized — split instead.36- Scratch notes: `ephemeral=true` (24h, never synced)37- Do NOT save: routine file reads, things in git, duplicates3839## Recall4041```42nmem_recall(query="project auth bug") # depth auto-detected43```4445- Causal queries ("why", "because", "caused") activate cause-effect chains46- Fixes auto-supersede errors (old errors demoted when fix is stored)47- Prefix queries with project name for accuracy4849## Smart Behaviors (automatic)5051- **Quality scoring**: specificity, structure, brevity scored per memory52- **Dedup**: similar memories flagged — use nmem_edit instead of duplicating53- **Causal synapses**: fixes create RESOLVED_BY links, demote old errors54- **Stale detection**: old-version references get -20% retrieval penalty55- **Cold demotion**: 0 access in 30d → cold; 90d → prune candidate (pinned exempt)56- **SimHash merge**: content-similar memories consolidated; 5+ group → summary fiber5758## Key Tools5960| Tool | When |61|------|------|62| `nmem_recall` | Query memories (depth auto-detected) |63| `nmem_context` | Load recent memories at session start |64| `nmem_recap` | Resume session (level=1-3, topic="X") |65| `nmem_session` | Track session state (get/set/end) |66| `nmem_edit` | Fix wrong type/content/priority |67| `nmem_forget` | Remove outdated memories (soft/hard) |68| `nmem_index` | Scan codebase into memory graph |69| `nmem_train` | Train docs into permanent knowledge |70| `nmem_health` | Brain grade + top penalties to fix |71| `nmem_explain` | Trace path between two concepts |72| `nmem_cognitive` | Hypotheses + predictions dashboard |7374All tools: `compact=true` saves 60-80% tokens.7576## Links7778- [GitHub](https://github.com/nhadaututtheky/neural-memory)79- [Documentation](https://nhadaututtheky.github.io/neural-memory)80- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=neuralmem.neuralmemory)
nhadaututtheky