mem — daily journal built on latent memory

Tiny markdown. Shared across all projects. Far fewer tokens than RAG.

mem is a daily journal that works for humans and AI coding agents on Windows, macOS, and Linux. It is deliberately simple so models read and write it without mistakes — and so you spend almost no context tokens.

I want to…	Read
Understand & use it for my own work (days → weeks)	GUIDE.md
Deep latent-memory idea	CONCEPT.md
Make AI agents use it correctly	templates/SKILL.md
See a full sample week	examples/sample-week/
Install only	sections below

~/mem/journal/2026-07-10.md
~/mem/journal/2026-07-11.md

One file per day. Plain Markdown. No database. No cloud. Python stdlib + git.

---

Built on the latent memory concept

Large language models already store general knowledge in their weights (their latent memory). They do not know your day, your decisions, or your open tasks.

So this journal never tries to re-teach the model what SQLite is, how JWT works, or how git works. It only stores the smallest cues the model cannot invent:

Store this (tiny)	Do not store this (huge, wasted)
what you did today on a project	full chat logs
what you decided and why	tutorials / docs the model already knows
open tasks, one line each	vector embeddings of whole repos
real numbers from a command run	“memory dumps” of every file

Example — one complete memory:

shopapp: decided: SQLite over Postgres — single-user desktop app

The model already knows the SQLite vs Postgres trade-offs. The only new fact is your choice and your reason. One line. The model expands it from latent knowledge when needed.

That is latent memory applied to personal history:

1. Model weights = world knowledge (free, already paid for in training)
2. Markdown cues = your specifics (tiny, day-ordered, shared)
3. Together = full understanding without a large memory file

Why models don’t mess it up

The format is intentionally dumb:

• one day = one .md file (YYYY-MM-DD.md)
• one event = one bullet line
• projects share the same journal (projectname: ... prefix)
• decisions use decided: … — why
• tasks use normal checkboxes - [ ] / - [x]

No schema, no JSON API, no special query language. Agents already speak They write a line; they read [SLEEP]/[DREAM] first, then a week with mem last 7 only if needed; they search with mem search shopapp:. Simple rules → fewer mistakes.

Day-wise order = easy follow-up

Days are chronological files. You (and the model) can:

• see what happened this week
• summarize progress across projects
• pick up open tasks without re-explaining the whole past

All projects share one memory home, so context is cross-project by default — not siloed per repo.

Token usage: latent cues vs RAG / chat dumps

Approach	What gets stuffed into the prompt	Tokens
Chat export “memory”	walls of old dialogue	very high
RAG / vector memory	retrieved chunks of docs + noise	high, every turn
Full project notes wiki	pages of prose the model already “knows”	high
mem (latent cues)	last few days of one-liners + open tasks	very low

You load a tiny day-wise dataset. The model fills in the rest from latent memory. That is the whole product.

---

Install — Windows, macOS, Linux

Requirements

Python 3.8+	python.org — on Windows tick “Add to PATH”
Git	git-scm.com
Optional	Obsidian — open your mem folder as a vault

macOS / Linux (one line)

curl -fsSL https://raw.githubusercontent.com/karmugilen/mem/main/setup.sh | bash

Windows (PowerShell, one line)

irm https://raw.githubusercontent.com/karmugilen/mem/main/setup.ps1 | iex

If script execution is blocked once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
irm https://raw.githubusercontent.com/karmugilen/mem/main/setup.ps1 | iex

From a clone (any OS)

git clone https://github.com/karmugilen/mem.git
cd mem

# macOS / Linux
./setup.sh

# Windows (PowerShell)
.\setup.ps1

What setup does

1. Installs the mem CLI on your PATH
2. Creates your data home (~/mem or %USERPROFILE%\mem) with journal/
3. git init so every write auto-commits (a backup you must remember isn’t a backup)
4. Installs short agent instructions (Claude / Grok / AGENTS.md) so AI tools use latent-cue style

Options (Unix):

./setup.sh --dir ~/Notes/mem   # custom data folder
./setup.sh --no-agents         # CLI + journal only
./setup.sh --agents-only       # re-install agent snippets
./setup.sh -y                  # non-interactive

Options (Windows PowerShell):

.\setup.ps1 -DataDir "$env:USERPROFILE\Notes\mem"
.\setup.ps1 -NoAgents
.\setup.ps1 -AgentsOnly

---

Quick start

mem log "myapp: got auth working, JWT"
mem log "myapp: decided: SQLite over Postgres — single-user desktop app"

mem task "myapp: fix JWT expiry check in auth.py"
mem tasks
mem done "JWT expiry"

# capture command output (cue + evidence)
pytest 2>&1 | mem log "myapp: tests: 3 fail, all JWT expiry"

# sleep / dream (same daily files — consolidate then rehearse)
mem sleep "myapp: stick with SQLite for single-user tools"
mem dream "myapp: multi-user later → Postgres migration risk"

# wake: compressed first, raw week only if needed
mem search "[SLEEP]"
mem search "[DREAM]"
mem tasks
mem last 7                 # only when sleep/dream are not enough
mem search decided:        # every decision
mem search myapp:          # one project’s whole history
mem path                   # where files live
mem edit                   # open today in your editor

Windows note: same commands in PowerShell or Command Prompt after setup (uses mem.cmd → Python).

---

Latent-memory writing rules

Keep the dataset tiny. The model will do the rest.

1. Cues, not content — name the thing; don’t paste a textbook
2. Always the WHY on decisions — decided: X — reason
3. Self-contained tasks — myapp: fix JWT expiry in auth.py, not fix bug
4. Project prefix — shared journal, searchable per project
5. Pipe outputs with a one-line conclusion — text = cue, block = evidence (auto-trimmed)
6. Sleep / dream — consolidate with mem sleep (2–3×/week), rehearse with mem dream after; same day files, [SLEEP] / [DREAM] prefixes only

---

For AI agents

When	Do this
Session start	mem search "[SLEEP]" → "[DREAM]" → mem tasks (then mem last 7 if needed)
Decision	mem log "proj: decided: X — why"
New work	mem task "proj: …"
Finished	mem done "…"
Result / failure	mem log "proj: …" or pipe output
Consolidate	mem sleep "proj: …"
Rehearse	mem dream "proj: …"

Agent files in templates/ (installed by setup):

File	Purpose
SKILL.md	Full agent skill — session protocol, formats, multi-week use
AGENTS.md	Short rules for any coding agent
CLAUDE.md.snippet	Global Claude instructions snippet

Also mirrored at skills/mem/SKILL.md for skill-style discovery.

Use it yourself over weeks: GUIDE.md
Concept depth: CONCEPT.md
Sample week of journal files: examples/sample-week/

---

Layout after install

macOS / Linux

~/.local/share/mem-tool/     # tool source
~/.local/bin/mem             # CLI
~/mem/                       # YOUR data (git, autocommit)
  journal/YYYY-MM-DD.md
  AGENTS.md

Windows

%LOCALAPPDATA%\mem-tool\     # tool source
%USERPROFILE%\.local\bin\mem.cmd
%USERPROFILE%\mem\           # YOUR data (git, autocommit)
  journal\YYYY-MM-DD.md
  AGENTS.md

Custom location:

# Unix
export MEM_HOME=~/Notes/mem

# Windows PowerShell
$env:MEM_HOME = "$env:USERPROFILE\Notes\mem"

---

Uninstall

Unix

rm -f ~/.local/bin/mem
rm -rf ~/.local/share/mem-tool
# delete ~/mem only if you also want your journal gone

Windows (PowerShell)

Remove-Item "$env:USERPROFILE\.local\bin\mem.cmd" -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\mem-tool" -Recurse -Force -ErrorAction SilentlyContinue
# Remove-Item "$env:USERPROFILE\mem" -Recurse -Force   # only if you want journal gone

---

License

MIT — see LICENSE.