@saleem11kh/repomem 0.3.1 → 0.4.0

package/README.md

@@ -37,7 +37,8 @@ your-project/
     ├── decisions/     ← architectural choices + why
     ├── sessions/      ← what was done, what's next
     ├── patterns/      ← reusable conventions for this codebase
-    └── issues/        ← known gotchas, do-not-repeat mistakes
+    ├── issues/        ← known gotchas, do-not-repeat mistakes
+    └── REPOMEM.md     ← auto-generated index of everything above
 ```
 
 Plain markdown files. No database. No cloud. No vendor lock-in.
@@ -48,63 +49,277 @@ Switch agents → same memory, because it's in the repo, not the tool.
 
 ---
 
-## How it works
+## Quick start
 
-repomem runs as an MCP server. Your AI agent gets 4 tools:
+```bash
+# 1. Install
+npm install -g @saleem11kh/repomem
 
-| Tool | What it does |
-|---|---|
-| `mem_save` | Save a decision, pattern, issue, or session note (with a one-line summary + `[[links]]`) |
-| `mem_search` | Search across all memory files instantly (BM25 + recency ranked) |
-| `mem_context` | Get a lean context packet at session start — summaries, not full bodies |
-| `mem_get` | Expand a single entry (by file or `[[wikilink]]`) only when you need it |
-| `mem_handoff` | Write today's session file, ready to commit |
-| `mem_prime` | Bootstrap memory on an existing repo from its CLAUDE.md / docs |
-
-At the start of every session, your agent calls `mem_context()` and immediately knows:
-- What was worked on last session
-- Key architectural decisions and why they were made
-- Patterns and conventions for this specific codebase
-- Known issues to avoid repeating
-- What's next
-
-To keep context small, `mem_context` returns **one-line summaries**; the agent expands
-only what it needs with `mem_get`. Entries can cross-link with `[[wikilinks]]`, so related
-decisions, patterns, and issues travel together. Already have a context-rich repo? Run
-`mem_prime` once to seed memory from your existing `CLAUDE.md` and `docs/`.
+# 2. Scaffold .repomem/ in your project
+cd your-project
+repomem init
+
+# 3. Wire it to your agent
+repomem setup claude-code     # or: cursor | gemini | codex
+
+# 4. Restart the agent, then approve the server when prompted
+```
+
+**Step 4 is not optional.** MCP servers are loaded when the agent starts, so a server
+wired mid-session does not exist in that session. Claude Code additionally requires
+you to approve any server declared in a project's `.mcp.json` the first time you
+launch with it.
+
+Verify with `/mcp` — you should see `repomem` connected with six tools. There are no
+slash commands to look for; MCP servers contribute **tools**, which never appear in
+the `/` menu.
 
 ---
 
-## Quick start
+## Usage
+
+### The six tools
+
+Your agent calls these; you don't type them.
+
+| Tool | Arguments | What it does |
+|---|---|---|
+| `mem_context` | `brief?` | Session-start packet: the last session, plus one-line summaries of decisions, patterns, and issues. Call it first. |
+| `mem_get` | `file` | Expand one entry in full — by `type/filename`, bare filename, or `[[wikilink]]` slug. |
+| `mem_search` | `query`, `linked?` | BM25 + recency ranked search across all memory. `linked=true` also searches linked repos and the workspace. |
+| `mem_save` | `type`, `title`, `content`, `summary?`, `tags?`, `links?`, `supersedes?`, `session?` | Write a `decision`, `pattern`, `issue`, or `session` note. |
+| `mem_handoff` | `summary`, `done?`, `next?`, `blockers?`, `session?`, `git?` | Close out a session so the next one picks up exactly where you left off. Fills in what changed from git. |
+| `mem_prime` | — | Bootstrap memory on an existing repo from its `CLAUDE.md` / `README.md` / `docs/`. Run once when adopting. |
+
+### Progressive disclosure — why context stays small
+
+`mem_context` deliberately returns **one-line summaries**, not full bodies. It runs at
+the start of every session; if it dumped everything, a repo with 50 memories would
+burn thousands of tokens before your first message.
+
+```
+## Recent decisions
+- BM25 + recency ranking instead of embeddings — Search is BM25 over raw markdown
+  with an exponential recency boost — no embeddings, zero extra deps.
+  (decisions/2026-07-26-bm25-recency-ranking-instead-of-embeddings.md)
+```
+
+The agent expands only what it needs with `mem_get`. This is why **every entry should
+have a `summary`** — it's the only thing most future sessions will ever read.
+
+### A normal session
+
+**At the start**, the agent calls `mem_context` and immediately knows what was worked
+on last, the key decisions and why, the conventions for this codebase, and known
+gotchas.
+
+**During work**, you capture things as they happen:
+
+> "Save that as a decision — include why we rejected the alternative."
+
+**At the end:**
+
+> "Run mem_handoff."
+
+Then commit. Nothing is shared with your team until you do:
 
 ```bash
-# Install
-npm install -g @saleem11kh/repomem
+git add .repomem/ && git commit -m "chore: update memory"
+```
 
-# Initialize in your project
-cd your-project
-repomem init
+### What to say
+
+repomem has no slash commands. You talk to your agent normally; it picks the tool.
 
-# Wire to Claude Code
+| You want | Say |
+|---|---|
+| Load context | *"What's in repomem for this project?"* |
+| Capture a choice | *"Save that as a decision, with why we rejected X"* |
+| Capture a convention | *"Save that as a pattern"* |
+| Capture a gotcha | *"Save that as an issue, with the guard against it"* |
+| Replace a stale decision | *"Save this as a decision that supersedes `<filename>`"* |
+| Sweep the whole session | *"Update repomem with what we did — skip anything obvious from the code"* |
+| Close out | *"Run mem_handoff"* |
+| Recall | *"Search repomem for how we handle retries"* |
+
+Adding **"skip anything obvious from the code"** matters — otherwise you accumulate
+entries restating function signatures, and the signal-to-noise ratio that makes memory
+worth loading degrades.
+
+### Adopting on an existing project
+
+`repomem init` gives you empty folders. To seed them from a repo that already has
+years of context:
+
+```bash
+cd your-existing-project
+repomem init
 repomem setup claude-code
+# restart the agent
+```
+
+Then, in the agent:
+
+> "Call `mem_prime`, then save what it surfaces as decisions, patterns, and issues."
+
+`mem_prime` gathers `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `README.md`, and
+`docs/**.md` (up to 12 files) and returns them with instructions to distil them into
+memory. **It writes nothing itself** — it needs an agent in the loop. Re-running it is
+safe: it reads the existing count first and is told not to duplicate.
+
+If your project has no docs, the higher-value move is to point the agent at the code:
+
+> "Read the source under `src/`, then save what you learned as decisions, patterns,
+> and issues. Give every entry a one-line summary and cross-link related entries."
+
+Aim for 5–12 entries. Fewer and `mem_context` says nothing useful; many more in one
+sitting and quality drops.
+
+### Handoffs are half-derived
+
+`mem_handoff` does not rely on the agent remembering what it touched. Since the
+session knows when it started, repomem asks git directly:
+
+```markdown
+## 2026-07-26 14:30 — Handoff
+
+Reworked how sessions are identified.
+
+_branch: master_
+
+**Committed this session:**
+- 1038eb6 fix(cli): route MCP config through cmd.exe on Windows
+- ce365ab chore(repomem): record the Windows MCP spawn gotcha
 
-# Wire to Cursor
-repomem setup cursor
+**Still uncommitted:**
+- M src/tools/mem-context.ts
+- ?? src/store/git.ts
 
-# Wire to Gemini CLI
-repomem setup gemini
+**Next:**
+- push the tag
 ```
 
-That's it. Your agent now has persistent memory that lives in your repo.
+The agent supplies only what git cannot know — *why*, and *what's next*. Commits and
+uncommitted files are facts, and deriving them is both cheaper and more reliable than
+asking a model to recall them.
 
+Notes:
+- Changes under `.repomem/` are filtered out; the handoff is writing there as it runs.
+- Long lists are capped at 20 with an explicit `…and N more`, never silently truncated.
+- Non-git projects, missing `git`, and empty repos all degrade quietly to a handoff
+  with no git detail. Pass `git: false` to skip it deliberately.
+- Commits are matched by *time*, so parallel sessions each report the same commits.
+  Time is the only signal available without asking agents to tag their own work.
+
+### Sessions and parallel agents
+
+Each session owns one file:
+
+```
+.repomem/sessions/2026-07-26-0917-windows-mcp-fix.md
+.repomem/sessions/2026-07-26-1430-auth-refactor.md
+```
+
+`YYYY-MM-DD-HHMM-<name>.md`, where the timestamp is when the session *started* — so it
+stays put as the session appends, and because it's zero-padded, filename order is
+chronological order.
+
+Name a session by passing `session` to `mem_save` or `mem_handoff` (*"run mem_handoff,
+call this session auth-refactor"*). Unnamed sessions are `untitled`; naming one later
+renames the file in place, so one session always maps to one file.
+
+This matters most when **more than one session runs at once** — two terminals, two
+agents, or two teammates:
+
+- Separate files mean no interleaving and **no git merge conflicts**
+- Sessions are linkable: a decision can point at `[[auth-refactor]]`
+- `mem_context` inlines the newest session and lists the others under **Also today**,
+  so parallel work is visible without being loaded in full
+- The connecting agent is recorded automatically (`agent: claude-code`), taken from the
+  MCP handshake — so parallel sessions from different tools are tellable apart
+
+### Anatomy of a memory file
+
+```markdown
 ---
+date: 2026-07-26
+summary: Search is BM25 over raw markdown with a recency boost — no embeddings.
+tags: [search, ranking]
+---
+# BM25 + recency ranking instead of embeddings
 
-## Multi-repo support
+Why not embeddings: they add a model dependency and a cache to invalidate, which
+breaks the "plain files, no infra" promise.
 
-Working across microservices or a multi-repo setup? repomem handles it.
+Related: [[memory-lives-in-the-repo-as-plain-markdown]]
+```
 
-```json
-// repomem.config.json
+- **`summary`** — the one line `mem_context` and `mem_search` show. Always set it.
+- **`tags`** — free-form, for retrieval.
+- **`supersedes`** — on a decision, the filename it replaces. Keeps the history.
+- **`[[wikilinks]]`** — resolve by slug regardless of date prefix. `mem_search` and
+  `mem_context` traverse them and show `→ related:`, so linked entries travel together.
+
+Filenames are `YYYY-MM-DD-<slug>.md`. The date prefix is load-bearing: it drives
+newest-first ordering and the search recency boost.
+
+### Editing and correcting
+
+There's no update tool. Two paths:
+
+- **Superseding a decision** — `mem_save` with `supersedes: <filename>` records the
+  replacement and keeps the history. This is the intended path.
+- **Fixing a mistake** — just edit the markdown file. It's plain text in your repo.
+
+⚠️ Saving twice on the same day with the same title **overwrites silently** — the
+filename is `date-slug` and `slugify` truncates at 60 characters, so two long titles
+sharing a prefix collide. Use short, distinct titles.
+
+---
+
+## CLI reference
+
+```
+repomem                      Start the MCP server (stdio) — how agents invoke it
+repomem init                 Scaffold .repomem/ and repomem.config.json
+repomem setup <agent>        Wire repomem into claude-code | cursor | gemini | codex
+repomem status               Show memory counts, configured agents, linked repos
+repomem sync                 Export all memory to stdout
+repomem import [file]        Import a sync bundle (file or stdin) into .repomem/
+repomem pull                 Fetch remote linked repos' memory from GitHub
+repomem help                 Show this help
+```
+
+`init` is idempotent — re-running it regenerates `REPOMEM.md` without touching config.
+
+`sync` and `import` are inverses, for airgapped transfer:
+
+```bash
+repomem sync > bundle.md          # on the connected machine
+repomem import bundle.md          # on the airgapped one
+```
+
+Where `setup` writes each agent's config:
+
+| Agent | File |
+|---|---|
+| Claude Code | `.mcp.json` (repo root — **not** `.claude/mcp.json`) |
+| Cursor | `.cursor/mcp.json` |
+| Gemini CLI | `.gemini/settings.json` |
+| Codex | `.codex/config.toml` |
+
+On Windows the generated command is wrapped in `cmd /c`, because agents spawn MCP
+servers without a shell and `npx` is a `.cmd` shim there. That makes the generated
+config **host-specific** — a teammate on macOS or Linux should re-run `repomem setup`
+to rewrite it.
+
+---
+
+## Multi-repo
+
+Working across microservices? Declare related repos in `repomem.config.json`:
+
+```jsonc
 {
   "project": "payments-service",
   "workspace": "../repomem-workspace",
@@ -117,19 +332,44 @@ Working across microservices or a multi-repo setup? repomem handles it.
 ```
 
 Linked repos can be **local paths** or **remote GitHub repos** (`github:owner/name`,
-optionally `#ref`). For remotes, run `repomem pull` once to fetch their `.repomem/`
-into a local, gitignored cache — no full clone needed. A `GITHUB_TOKEN`/`GH_TOKEN`
-env var is used for private repos and higher rate limits.
+optionally `#ref`). For remotes, run `repomem pull` once — it fetches only their
+`.repomem/` subtree through the GitHub API into a local, gitignored cache. No full
+clone. Set `GITHUB_TOKEN`/`GH_TOKEN` for private repos and higher rate limits.
+
+Then `mem_search` with `linked=true` searches current + linked + remote + workspace,
+ranked together and labelled by source:
 
-When your agent calls `mem_search` with `linked=true`, repomem searches:
-1. Current repo memory
-2. Linked repo memory — local paths and pulled remotes (contracts, shared patterns)
-3. Workspace memory (org-wide decisions)
+```
+[current] [linked:auth-service] [remote:billing-svc] [workspace]
+```
+
+Pull is explicit and manual — nothing refreshes in the background.
+
+---
+
+## Troubleshooting
+
+**"I don't see any repomem commands."**  
+Expected. MCP servers contribute tools, not slash commands. Check `/mcp` instead — it
+should list `repomem` as connected with six tools.
 
-Results are ranked (TF-IDF + recency) and labelled by source:
-`[current] [linked:auth-service] [remote:billing-svc] [workspace]`
+**`/mcp` shows repomem as failed or missing.**  
+Three causes, in order of likelihood:
+1. You haven't restarted the agent since running `repomem setup`.
+2. The project's `.mcp.json` was never approved — the prompt only fires at startup.
+3. You're on Windows with a config generated by repomem ≤ 0.3.0, which used a bare
+   `npx` command that cannot be spawned without a shell. Re-run `repomem setup`.
 
-Cross-repository context that actually travels with the code — not locked in a personal tool on one machine.
+**Tools appear but every call says `.repomem/ not found`.**  
+The server resolves the project root by walking up for `.repomem/` or
+`repomem.config.json`. Run `repomem init` at the repo root.
+
+**Working on repomem itself?** Point `.mcp.json` at your local build so you exercise
+your changes rather than the published package:
+
+```json
+{ "mcpServers": { "repomem": { "command": "node", "args": ["dist/cli.js"] } } }
+```
 
 ---
 
@@ -149,38 +389,49 @@ Cross-repository context that actually travels with the code — not locked in a
 
 ## Roadmap
 
-- [x] npm package claimed
 - [x] `repomem init` — scaffold `.repomem/` in any project
-- [x] 4 core MCP tools (`mem_save`, `mem_search`, `mem_context`, `mem_handoff`)
-- [x] Claude Code wiring (`repomem setup claude-code`)
-- [x] Cursor wiring
-- [x] Gemini CLI / Codex wiring
-- [x] Multi-repo `linked` support (local paths)
+- [x] Six MCP tools (`mem_save`, `mem_search`, `mem_context`, `mem_get`, `mem_handoff`, `mem_prime`)
+- [x] Claude Code, Cursor, Gemini CLI, and Codex wiring
+- [x] Multi-repo `linked` support — local paths and remote GitHub repos
 - [x] Workspace scope (cross-org shared memory repo)
-- [x] `repomem sync` — export `.repomem/` to stdout for sharing
-- [x] Remote linked repos (read `.repomem/` from GitHub without cloning, via `repomem pull`)
-- [x] `repomem import` — import a sync bundle for airgapped environments
-- [x] Smarter search ranking (BM25 + recency weighting)
+- [x] `repomem sync` / `import` for airgapped transfer
+- [x] BM25 + recency search ranking
 - [x] Progressive disclosure — `mem_context` summaries + `mem_get` to expand
-- [x] `[[wikilink]]` graph between memories (traversed by search + context)
+- [x] `[[wikilink]]` graph between memories
 - [x] `mem_prime` — bootstrap memory from an existing repo's docs
+- [x] One file per session, with names, timestamps, and agent attribution
+- [x] Git-derived handoffs — "what changed" comes from commits, not recollection
+- [ ] `init` learns the repo — stack, commands, layout, ADRs, and git conventions, without an LLM
+- [ ] `repomem prime` as a CLI, so onboarding can be scripted end-to-end
+- [ ] Auto-capture hooks, so memory does not depend on remembering to ask
+- [ ] Task-scoped `mem_context` and a token budget, for repos with lots of memory
 - [ ] Optional semantic search layer (off by default, local embedding cache)
 
 ---
 
 ## Status
 
-**v0.2 — working.** `init`, `setup`, `status`, `sync`, `import`, `pull`, and six
-MCP tools (`mem_save`, `mem_search`, `mem_context`, `mem_get`, `mem_handoff`,
-`mem_prime`) are implemented and tested. Context is token-lean by default
-(summaries + `mem_get` to expand), memories cross-link with `[[wikilinks]]`, and
-`mem_prime` bootstraps an existing repo from its docs. Multi-repo search spans
-local `linked` paths, remote GitHub repos (pulled into a local cache), and a
-shared `workspace`, ranked by BM25 with a recency boost.
+**v0.3.1 — working.** `init`, `setup`, `status`, `sync`, `import`, `pull`, and six MCP
+tools are implemented and covered by tests. Context is token-lean by default, memories
+cross-link with `[[wikilinks]]`, `mem_prime` bootstraps an existing repo from its docs,
+and multi-repo search spans local paths, pulled GitHub remotes, and a shared workspace.
+
+**On `master`, not yet published:** one file per session
+(`YYYY-MM-DD-HHMM-<name>.md`) with front matter, session naming, agent attribution
+from the MCP handshake, `mem_context` listing parallel same-day sessions, and
+git-derived handoffs. Landing in v0.4.
+
+**The known gap:** nothing is recorded unless the agent is asked. MCP servers are
+passive — they act only when a tool is called. Git-derived handoffs remove the recall
+burden once a handoff is requested, but *requesting* it is still manual. Auto-capture
+hooks are the planned fix.
 
-If this solves a problem you have, **star the repo** — it helps validate that this is worth building and tells me which features to prioritise first.
+If this solves a problem you have, **star the repo** — it helps validate that this is
+worth building and tells me which features to prioritise.
 
-Have this exact problem on your team? Open an [issue](https://github.com/saleem786khan/repomem/issues) describing your setup — I'm using real use cases to shape the v0.1 feature set.
+Have this exact problem on your team? Open an
+[issue](https://github.com/saleem786khan/repomem/issues) describing your setup — I'm
+using real use cases to shape the roadmap.
 
 ---
 
@@ -192,11 +443,10 @@ repomem is being built in public. Contributions welcome at any stage.
 git clone https://github.com/saleem786khan/repomem
 cd repomem
 npm install
-npm run dev
+npm test        # builds, then runs the suite
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.  
-Good first issues will be labelled once the scaffold is up.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
 
 ---
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4BA,yDAAyD;AACzD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAgDjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,yDAAyD;AACzD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAwDjD"}

package/dist/index.js

@@ -11,6 +11,7 @@ const mem_context_js_1 = require("./tools/mem-context.js");
 const mem_handoff_js_1 = require("./tools/mem-handoff.js");
 const mem_get_js_1 = require("./tools/mem-get.js");
 const mem_prime_js_1 = require("./tools/mem-prime.js");
+const session_js_1 = require("./tools/session.js");
 const TOOLS = [
     mem_save_js_1.memSave,
     mem_search_js_1.memSearch,
@@ -20,7 +21,7 @@ const TOOLS = [
     mem_prime_js_1.memPrime,
 ];
 const TOOL_MAP = new Map(TOOLS.map((t) => [t.name, t]));
-const VERSION = "0.3.1";
+const VERSION = "0.4.0";
 /** Build and start the repomem MCP server over stdio. */
 async function startServer() {
     const server = new index_js_1.Server({ name: "repomem", version: VERSION }, {
@@ -32,6 +33,14 @@ async function startServer() {
             "recall, and mem_handoff to close out a session. On a project new to " +
             "repomem, call mem_prime once to bootstrap memory from existing docs.",
     });
+    // Attribute session memory to whichever agent connected. The client announces
+    // itself in `initialize`, so this costs nothing and makes parallel sessions
+    // from different agents tellable apart.
+    server.oninitialized = () => {
+        const client = server.getClientVersion();
+        if (client?.name)
+            (0, session_js_1.setSessionAgent)(client.name);
+    };
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         tools: TOOLS.map((t) => ({
             name: t.name,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AA8BA,kCAwDC;AAtFD,wEAAmE;AACnE,wEAAiF;AACjF,iEAG4C;AAE5C,kDAAqD;AAErD,qDAA8C;AAC9C,yDAAkD;AAClD,2DAAoD;AACpD,2DAAoD;AACpD,mDAA4C;AAC5C,uDAAgD;AAChD,mDAAqD;AAErD,MAAM,KAAK,GAAc;IACvB,qBAAO;IACP,yBAAS;IACT,2BAAU;IACV,2BAAU;IACV,mBAAM;IACN,uBAAQ;CACT,CAAC;AACF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAExD,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,yDAAyD;AAClD,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,IAAI,iBAAM,CACvB,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,EACrC;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,YAAY,EACV,2EAA2E;YAC3E,6EAA6E;YAC7E,uEAAuE;YACvE,yEAAyE;YACzE,sEAAsE;YACtE,sEAAsE;KACzE,CACF,CAAC;IAEF,8EAA8E;IAC9E,4EAA4E;IAC5E,wCAAwC;IACxC,MAAM,CAAC,aAAa,GAAG,GAAG,EAAE;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QACzC,IAAI,MAAM,EAAE,IAAI;YAAE,IAAA,4BAAe,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACvB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;SAC3B,CAAC,CAAC;KACJ,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,iBAAiB,CAAC,gCAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAChE,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC3E,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAA4B,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAA,2BAAe,GAAE,CAAC,CAAC;YACnD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC,IAAI,YAAY,OAAO,EAAE,EAAE,CAAC;gBACtE,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,qEAAqE;IACrE,OAAO,CAAC,KAAK,CAAC,uBAAuB,OAAO,iBAAiB,CAAC,CAAC;AACjE,CAAC;AAED,+EAA+E;AAC/E,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC1B,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,GAAG,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/store/file-store.d.ts

@@ -18,7 +18,7 @@ export declare function getRepomemRoot(projectRoot?: string): string;
 export declare function isInitialized(projectRoot?: string): boolean;
 /**
  * List relative file paths (from .repomem/) of a given memory type, sorted
- * newest-first by filename. Returns [] when uninitialised or empty.
+ * newest-first. Returns [] when uninitialised or empty.
  */
 export declare function listFiles(type: MemoryType, projectRoot?: string): string[];
 /** Read a memory file by type + filename. Returns null when missing. */

package/dist/store/file-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../src/store/file-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../src/store/file-store.ts"],"names":[],"mappings":"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"}

package/dist/store/file-store.js

@@ -70,9 +70,24 @@ function getRepomemRoot(projectRoot = (0, config_js_1.findProjectRoot)()) {
 function isInitialized(projectRoot = (0, config_js_1.findProjectRoot)()) {
     return fs.existsSync(getRepomemRoot(projectRoot));
 }
+/**
+ * Chronological sort key for a memory filename: its `YYYY-MM-DD` prefix plus the
+ * `HHMM` that session files carry.
+ *
+ * Sorting raw names would be wrong here: `-` (0x2D) sorts before `.` (0x2E), so
+ * a legacy whole-day `2026-07-26.md` would outrank `2026-07-26-0917-x.md` from
+ * the same date and be mistaken for the newer file. Legacy day files get `0000`
+ * so any timed session that day counts as newer.
+ */
+function fileOrderKey(filename) {
+    const m = filename.match(/^(\d{4}-\d{2}-\d{2})(?:-(\d{4})(?=-|\.))?/);
+    if (!m)
+        return "0000-00-00-0000";
+    return `${m[1]}-${m[2] ?? "0000"}`;
+}
 /**
  * List relative file paths (from .repomem/) of a given memory type, sorted
- * newest-first by filename. Returns [] when uninitialised or empty.
+ * newest-first. Returns [] when uninitialised or empty.
  */
 function listFiles(type, projectRoot = (0, config_js_1.findProjectRoot)()) {
     const dir = path.join(getRepomemRoot(projectRoot), type);
@@ -80,7 +95,11 @@ function listFiles(type, projectRoot = (0, config_js_1.findProjectRoot)()) {
         return fs
             .readdirSync(dir)
             .filter((f) => f.endsWith(".md"))
-            .sort()
+            .sort((a, b) => {
+            const ka = fileOrderKey(a);
+            const kb = fileOrderKey(b);
+            return ka === kb ? a.localeCompare(b) : ka < kb ? -1 : 1;
+        })
             .reverse();
     }
     catch {
@@ -169,9 +188,15 @@ function parseLinks(raw) {
         out.add(m[1].trim());
     return [...out];
 }
-/** Strip the date prefix and extension from a memory filename to get its slug. */
+/**
+ * Strip the date (and, for session files, the HHMM) prefix and the extension to
+ * get a memory's slug — the thing [[wikilinks]] match against.
+ */
 function fileSlug(filename) {
-    return filename.replace(/\.md$/i, "").replace(/^\d{4}-\d{2}-\d{2}-?/, "").toLowerCase();
+    return filename
+        .replace(/\.md$/i, "")
+        .replace(/^\d{4}-\d{2}-\d{2}-?(?:\d{4}-)?/, "")
+        .toLowerCase();
 }
 /**
  * Resolve a `[[target]]` to a memory file. Matches an exact filename, an exact