Skip to content

Mobile Memory

Salman Ashraf edited this page Oct 9, 2026 · 1 revision

Mobile Memory

Mobile Memory is a mobile-specific AI memory and knowledge graph system for Mobile AI Agents. It captures project architecture, session decisions, agent findings, health risks, code state, and the next executable action into local project memory and a portable MOBILE_MEMORY.md handoff file.

The goal is simple: when tokens run out or a developer switches tools, the next AI session can continue without asking for the same explanation again.


Why It Exists

Generic AI coding sessions lose context:

  • Architecture decisions vanish between sessions.
  • Agent findings from AXIOM, CRASHER, DART, SWIFT, and BRIDGE are forgotten.
  • Mid-edit files become risky because the next AI cannot see what was already decided.
  • Large codebases cost too many tokens to reload from scratch.

Mobile Memory preserves the mobile-specific parts of context that matter most:

  • ViewModels, repositories, use cases, widgets, screens, services, APIs, databases, tests
  • Edges like OBSERVES, CALLS, INJECTS, EMITS, NAVIGATES_TO, and VIOLATES
  • CRITICAL/WARNING/DEBT health nodes
  • The exact NEXT ACTION

Token Reduction Math

Mobile Memory reduces tokens by replacing raw files with a graph and a session state summary.

Typical Android feature:

Source Files Avg tokens Total
Compose screens 4 2,500 10,000
ViewModels 3 2,000 6,000
Use cases 5 700 3,500
Repositories 3 1,800 5,400
API/DAO/models 12 600 7,200
Tests 8 1,200 9,600
Prior chat context 1 18,000 18,000
Total raw context 36 - 59,700

A high-quality Mobile Memory checkpoint for the same feature is usually 700-1,200 tokens:

59,700 raw tokens / 750 Mobile Memory tokens = 79.6x reduction

That is where the "up to 80x" claim comes from. Smaller snippets reduce less. Large mobile features reduce more because repeated code bodies collapse into graph nodes, edges, health findings, and decisions.


How It Differs From Generic Memory Tools

Tools like Recallium, mem0, and agentmemory are useful generic memory layers. Mobile Memory is different because it understands mobile architecture.

Generic memory tools Mobile Memory
Store arbitrary facts Stores mobile architecture state
Remember text snippets Builds UI/VM/Domain/Data/Net/DB graphs
Need manual meaning Knows ViewModel, ObservableObject, StateNotifier, Context, MonoBehaviour
Generic links Mobile edge types: OBSERVES, EMITS, NAVIGATES_TO, VIOLATES
Generic risk Flags GlobalScope, force unwraps, exposed MutableStateFlow, bridge hot paths, Update() abuse
Session recall Session recall plus executable NEXT ACTION

Mobile Memory has two layers:

Layer Storage Purpose
Local memory .mobile-ai-agents/memory/events.jsonl Persistent project event history for search, timeline, and context injection
Portable checkpoint MOBILE_MEMORY.md Tool-agnostic handoff file that any AI can read

Raw local memory stays out of git by default. Commit MOBILE_MEMORY.md only when the context is useful for review, handoff, or long-running work.


Local Memory Store

Initialize memory inside any app project:

npx mobile-ai-agents memory init

This creates:

.mobile-ai-agents/
├── .gitignore
└── memory/
    ├── config.json
    ├── events.jsonl
    └── index.md

Capture memory events:

npx mobile-ai-agents memory capture --type decision --title "Use Room" --text "Persist habits locally with Room."
npx mobile-ai-agents memory capture --type finding --title "PRD gap" --text "Restart persistence is missing."
npx mobile-ai-agents memory capture --type next-action --text "Implement HabitDao and restart persistence test."

You can also pipe content:

git diff | npx mobile-ai-agents memory capture --type code-state --title "Current diff"

Search and inject context:

npx mobile-ai-agents memory search persistence
npx mobile-ai-agents memory timeline --limit 20
npx mobile-ai-agents memory inject

Generate the portable checkpoint:

npx mobile-ai-agents memory checkpoint

This writes MOBILE_MEMORY.md from the captured memory events. Review it before committing.

Privacy rule: do not capture secrets, customer data, private logs, tokens, credentials, or proprietary crash payloads. Text inside <private>...</private> is removed during capture.


Quick Save Slash Command

Use /mobile-memory-save when you are inside Claude Code and need a fast checkpoint without setting up the full local memory store.

/mobile-memory-save

Recommended input:

PROJECT: Habit Pulse
PLATFORM: Android
CURRENT TASK:
Building habit tracker MVP with list, add habit, streak tracking.

DECISIONS:
- Use Room for offline storage.
- Use MVVM with StateFlow.
- Keep UI simple for demo.

PROGRESS:
- Done: habit list screen and add habit dialog.
- In progress: persistence and restart test.
- Blocked: none.

CODE STATE:
MainActivity.kt has current UI. Habit data is still in memory.

NEXT ACTION:
Add Room HabitEntity, HabitDao, and repository, then persist created habits across app restart.

The skill returns a compact MOBILE_MEMORY.md. Save it in the project root when the handoff should travel with the app. A future session can continue with:

Read MOBILE_MEMORY.md and continue from NEXT ACTION.
Need Use
Fast one-time checkpoint inside chat /mobile-memory-save
Searchable project memory over days/weeks npx mobile-ai-agents memory init/capture/search/checkpoint
Resume a new session from saved context /mobile-memory or Read MOBILE_MEMORY.md and continue

Mobile Flight Recorder

Mobile Flight Recorder is the end-of-session workflow for turning Mobile Memory into a project-level handoff file named MOBILE_AGENCY_CONTEXT.md.

Use it when a session produced decisions, fixes, bugs, device proof, PR links, or a next task that must survive across AI tools. It records:

  • App goal, platform, stack, repo, and active branch
  • Architecture and implemented features
  • Current task and pending tasks
  • Known bugs, risks, and evidence
  • Test/build commands that actually ran
  • Device, emulator, simulator, or Mobile MCP setup
  • Agent findings, decisions, changed files, and links
  • Exactly one next recommended action

Run it with:

Run Mobile Flight Recorder. Update MOBILE_AGENCY_CONTEXT.md and MOBILE_MEMORY.md if useful. Capture decisions, files changed, tests run, known bugs, device setup, links, and exactly one Next Recommended Action. Do not include secrets.

Resume any AI tool with:

Read MOBILE_AGENCY_CONTEXT.md and MOBILE_MEMORY.md if present. Continue from Next Recommended Action. Inspect changed files before editing and update the flight recorder before stopping.

Use MOBILE_MEMORY.md for compact memory and MOBILE_AGENCY_CONTEXT.md for the broader project flight recorder.


Graphify Integration

Graphify can be used first to create a general graph of a project. Mobile Memory enhances that output with mobile semantics:

  1. Run Graphify to discover broad dependency structure.
  2. Run /mobile-memory graph on the relevant mobile files.
  3. Merge Graphify's broad nodes with Mobile Memory's mobile-specific node types and health labels.
  4. Save the result in MOBILE_MEMORY.md.

Mobile Memory uses confidence tags similar to graph-first tools:

  • EXTRACTED: direct code evidence exists
  • INFERRED: relationship is strongly implied
  • AMBIGUOUS: relationship may exist but needs more code

Portable Checkpoint Format

---
# Mobile Memory
**Project:** [name]
**Platform:** [Android/iOS/Flutter/RN/Unity/Unreal]
**Stack:** [language, framework, key libraries]
**Architecture:** [pattern]
**Saved:** [date]
**Compatible:** Claude Code · Cursor · Windsurf · ChatGPT · Gemini · Copilot
**Token reduction:** [X× vs reading raw files]

---

## ⚡ INSTANT RESUME
[2-4 sentences. Fully self-contained. No assumed knowledge. What project, what task, what decisions, what to do next.]

---

## 🗺️ Knowledge Graph

### Nodes
| Node | Type | Layer | Health |
|---|---|---|---|
| [ClassName] | [VM/REPO/UI/etc] | [UI/Domain/Data] | [OK/CRITICAL/WARNING] |

### Key Edges
| From | Edge | To | Note |
|---|---|---|---|
| [Node] | OBSERVES | [Node] | [why this matters] |

### God Nodes
| Node | Connections | Platform Risk | Recommendation |
|---|---|---|---|

### Architecture Violations
- [Class] VIOLATES [rule] — [explanation] → [fix]

---

## 🏥 Health Report
### 🚨 CRITICAL
- [Node]: [issue] → [fix]

### ⚠️ WARNING
- [Node]: [issue] → [fix]

### 🏦 Tech Debt
- [Node]: [debt] → [migration path]

---

## 🎯 Session Context

### Current Task
[Exact task in one paragraph]

### Decisions Made
| Decision | Reason | Rejected |
|---|---|---|

### Progress
✅ Done: [list]
🔄 In Progress: [exact state of anything mid-edit]
⏭️ NEXT ACTION: [specific, executable, no assumed context]
🚧 Blocked: [list or "Nothing"]

### Open Questions
- [question 1]
- [question 2]

---

## 🤖 Agent State
| Agent | Last Action | Finding | Pending |
|---|---|---|---|
| AXIOM | [what it reviewed] | [what it found] | [what remains] |

---

## 📄 Code State
[For any file mid-edit, paste current state here]

---

## 🔄 Resume Instructions

**Claude Code:**
Start new session → paste INSTANT RESUME → paste full MOBILE_MEMORY.md → say "Continue"

**Cursor/Windsurf:**
Save as MOBILE_MEMORY.md in project root → next prompt: "Read MOBILE_MEMORY.md and continue"

**ChatGPT/Gemini:**
Paste full file as first message → "Resume from NEXT ACTION"

**Same tool, new session:**
Paste full file → /mobile-memory restore
---

Commands

Preferred CLI:

Command Use
mobile-ai-agents memory init Create local project memory
mobile-ai-agents memory capture Save decisions, findings, progress, and next actions
mobile-ai-agents memory search Search local project memory
mobile-ai-agents memory timeline Show recent memory events
mobile-ai-agents memory inject Print compact context for a new AI session
mobile-ai-agents memory checkpoint Generate MOBILE_MEMORY.md

Legacy slash aliases:

Command Use
/mobile-memory save Produce full MOBILE_MEMORY.md
/mobile-memory restore Load a pasted MOBILE_MEMORY.md and continue
/mobile-memory graph Build the knowledge graph from code files
/mobile-memory-search Search local .mobile-ai-agents/memory/ output and continue from relevant context
/mobile-memory update Update an existing checkpoint
/mobile-memory status Print only progress state
/mobile-memory health Print CRITICAL and WARNING nodes
/mobile-memory next Print only NEXT ACTION
/mobile-memory decisions Print decisions from the session
/mobile-memory diff Show changes since last save

FAQ

Is Mobile Memory a replacement for reading code?

No. It is a resume layer. Use it to restore context quickly, then read the exact files needed for the next action.

Should MOBILE_MEMORY.md be committed?

Commit MOBILE_MEMORY.md when the context is useful for handoff, review, or long-lived work. Do not commit .mobile-ai-agents/memory/events.jsonl unless your team explicitly wants raw local event history in source control. Do not commit secrets, private logs, customer data, or proprietary crash payloads.

How often should I capture memory?

Capture memory after major architectural decisions, after agent findings, before switching tools, and when the session is long enough that re-explaining would be expensive.

Why does it include health nodes?

Mobile projects fail at boundaries: lifecycle, state ownership, navigation, threading, persistence, and platform APIs. Health nodes preserve those risks so the next AI does not repeat unsafe work.

Can ChatGPT or Gemini use it?

Yes. Paste the full file as the first message and say: "Resume from NEXT ACTION." Mobile Memory checkpoints are plain Markdown and do not depend on a specific AI tool.

Clone this wiki locally