Merge pull request #3 from hacklmdev/dev

Dev

Author: vchan-in

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 *.vsix
 site/
+.memory/cleanup.log

.memory/cleanup.log

@@ -34,12 +34,10 @@ Memories stored by HackLM Memory.
 
 - [docs-site-zensical] Docs site uses Zensical (pip install zensical). Config in zensical.toml at repo root. Serve: .venv/Scripts/zensical.exe serve. Build: zensical build → site/. Deploys to GitHub Pages via .github/workflows/docs.yml on push to main.
 
-
 - [globalstate-keys-file] All globalState keys live in extension/src/globalStateKeys.ts as named exports. Never use bare string literals for globalState keys elsewhere.
 
 - [category-limits-source] CATEGORY_LIMITS constant removed from markdownStore.ts. Category limits come from VS Code config only (package.json defaults via config.get). Default fallback is hardcoded as 20 in utils.ts.
 
-- [stale-slug-pruner-removed] pruneStaleEntries removed from cleanupMemory.ts. Stale slugs last-cleanup and last-session-debrief no longer exist. ADRs 0001 and 0013 deleted from docs/decisions/ as they documented completed migration periods.
-
-
 - [adr-location] ADRs live in docs/decisions.md but are NOT in the Zensical nav. The nav has an ADR page (docs/adr.md) instead. That page links back to docs/decisions.md on GitHub.
+
+- [category-limits-defaults] Category defaults doubled: Instruction/Security = 30, Quirk/Preference/Decision = 40. Schema maximum raised to 100. Fallback in utils.ts and UI validation cap updated to match.

.memory/decisions.md

@@ -9,3 +9,5 @@ Memories stored by HackLM Memory.
 - [empty-justification] Passing an empty options object to sendRequest suppresses the justification string in the VS Code permission prompt. The user sees a blank reason. Always pass a justification.
 
 - [adr-location] ADRs live in docs/decisions.md (a single flat file, not a directory). No separate per-ADR files. Add new ADRs as new H2 sections at the bottom of that file.
+
+- [wx-flag-advisory-lock] The outer cross-process lock uses fs.open with the wx flag to create the lockfile exclusively. If the file already exists the open fails, signaling another process holds the lock. Never use a different open mode for this file.

.memory/quirks.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-02-28
+
+### Added
+
+- Two-tier write locking: cross-process advisory lockfile (`crossProcessLock.ts`) stacked over per-file in-process promise queue — prevents concurrent writes from multiple VS Code windows
+- Plan agent patching: `patchPlanAgent()` injects `queryMemory` + `storeMemory` into the Copilot Chat Plan agent on every activation (idempotent)
+
+### Changed
+
+- Default category limits doubled: Instruction/Security 15→30, Quirk/Preference/Decision 20→40
+- Configurable maximum raised from 50 to 100
+
 ## [1.0.0] - 2026-02-27
 
 ### Added
@@ -30,7 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Per-category entry limit settings
 - Getting Started walkthrough (5 steps)
 - esbuild single-file bundle (`dist/extension.js`) — no webpack
-- Publishes to VS Marketplace and Open VSX (compatible with VS Code and Google Antigravity)
+- Publishes to VS Marketplace and Open VSX
 
 [Unreleased]: https://github.com/hacklmdev/memory/compare/v1.0.0...HEAD
 [1.0.0]: https://github.com/hacklmdev/memory/releases/tag/v1.0.0

CHANGELOG.md

@@ -5,7 +5,7 @@ Thank you for your interest in contributing.
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) 20+
-- [VS Code](https://code.visualstudio.com/) 1.99+ (or any Open VSX-compatible editor, e.g. Google Antigravity)
+- [VS Code](https://code.visualstudio.com/) 1.99+
 - Git
 
 ## Build

CONTRIBUTING.md

@@ -17,13 +17,27 @@ A long-term memory layer for VS Code Copilot — learn from interactions, retain
 
 ## Compatibility
 
-Works in any Open VSX-compatible editor:
+Requires [VS Code](https://code.visualstudio.com/) 1.99+.
 
-- [VS Code](https://code.visualstudio.com/) 1.99+
-- [Google Antigravity](https://antigravity.google/) (Open VSX)
-- [Gitpod](https://gitpod.io/) (Open VSX)
+Also published to [Open VSX](https://open-vsx.org/extension/hacklm/hacklm-memory) for editors that use the Open VSX registry.
 
-> **Note:** The memory LM tools (`storeMemory`, `queryMemory`) require the editor to implement the VS Code LM Tool API. Editors that do not implement this API will install the extension but the tools will not be available in chat.
+### Open VSX editors
+
+In Open VSX-compatible editors the extension installs and activates. What works depends on whether the editor implements the VS Code LM Tool API:
+
+| Feature | Available |
+|---------|----------|
+| `.memory/*.md` files created on first open | Always |
+| `copilot-instructions.md` reference block injected | Always |
+| `storeMemory` / `queryMemory` LM tools | VS Code LM Tool API required |
+| Tree view, status bar, control panel | VS Code only |
+| LM deduplication and gap analysis | VS Code LM Tool API required |
+
+The `.memory/` files and `copilot-instructions.md` pointer are set up regardless of editor. Once those exist, any AI agent that reads instruction files can access the memory store directly — even without the LM tools.
+
+The full experience (LM tools, UI) requires VS Code 1.99+.
+
+Support for additional editors via MCP is planned — see the [Roadmap](docs/roadmap.md).
 
 ## Architecture
 
@@ -78,7 +92,7 @@ npm run build
 | `hacklm-memory.lmFamily` | `gpt-5-mini` | Copilot model family for LM operations |
 | `hacklm-memory.autoApproveStore` | `false` | Skip confirmation prompt when saving memories |
 | `hacklm-memory.manageInstructionFile` | `true` | Allow the extension to manage `.github/copilot-instructions.md` |
-| `hacklm-memory.categoryLimit.*` | varies | Per-category max entry counts |
+| `hacklm-memory.categoryLimit.*` | varies (30–40) | Per-category max entry counts |
 
 ## Privacy
 
@@ -94,7 +108,7 @@ Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before
 - [Architecture](docs/architecture.md) — module map, data flow, key design decisions
 - [API Reference](docs/api-reference.md) — LM tool schemas, memory file format
 - [Developer Guide](docs/contributing.md) — how to add categories, tools, and tests
-- [Architecture Decision Records](docs/decisions.md) — 16 ADRs covering every major decision
+- [Architecture Decision Records](docs/decisions.md) — 17 ADRs covering every major decision
 - [Roadmap](docs/roadmap.md) — planned work and open contribution areas
 
 ## License

README.md

@@ -32,9 +32,9 @@ This makes the codebase predictable. When LM behaviour changes, you edit one fil
 
 ## 4. Editor-agnostic storage
 
-The `.memory/*.md` file format is the stable contract — not VS Code, not TypeScript, not this extension. A future JetBrains plugin or Neovim integration must read and write the same format for memory to be shareable across editors.
+The `.memory/*.md` file format is the stable contract — not VS Code, not TypeScript, not this extension. Any future port (JetBrains plugin, Neovim integration, MCP server for Google Antigravity) must read and write the same format for memory to be shareable across editors.
 
-The storage layer (`dedup.ts`, `scoring.ts`, `search.ts`, `markdownStore.ts`) has no VS Code dependency and must stay that way.
+The storage layer (`dedup.ts`, `scoring.ts`, `search.ts`, `markdownStore.ts`) has no VS Code dependency and must stay that way. When additional editor support is built, this layer is extracted to `packages/storage` and shared — not copied.
 
 ---
 

docs/adr.md

@@ -116,11 +116,11 @@ Returns `"No memories found."` if no entries match.
 
 | Category | File | Default Limit | What It Stores |
 |----------|------|---------------|----------------|
-| `Instruction` | `.memory/instructions.md` | 15 | How Copilot should behave |
-| `Quirk` | `.memory/quirks.md` | 20 | Project-specific weirdness — non-obvious gotchas |
-| `Preference` | `.memory/preferences.md` | 20 | Style, tone, and design choices |
-| `Decision` | `.memory/decisions.md` | 20 | Architectural commitments |
-| `Security` | `.memory/security.md` | 15 | Rules that must never be broken |
+| `Instruction` | `.memory/instructions.md` | 30 | How Copilot should behave |
+| `Quirk` | `.memory/quirks.md` | 40 | Project-specific weirdness — non-obvious gotchas |
+| `Preference` | `.memory/preferences.md` | 40 | Style, tone, and design choices |
+| `Decision` | `.memory/decisions.md` | 40 | Architectural commitments |
+| `Security` | `.memory/security.md` | 30 | Rules that must never be broken |
 
 Limits are configurable per-category via `hacklm-memory.categoryLimit.<Category>` settings.
 

docs/api-reference.md

@@ -69,9 +69,17 @@ flowchart TD
 
 ## Key Design Decisions
 
-### Per-file Mutex Locks
+### Two-tier Write Locks
 
-`markdownStore.ts` maintains a `Map<filePath, Promise<void>>` as a chained promise queue. Every read-then-write operation on a `.memory/*.md` file acquires the lock for that specific file. This prevents concurrent `storeMemory` calls and background cleanup from corrupting the same file simultaneously.
+Every write to `.memory/*.md` goes through two stacked locks:
+
+1. **Outer — cross-process advisory lockfile** (`crossProcessLock.ts`): `withCrossProcessLock(memoryDir, fn)` creates `.memory/.lock` with an exclusive `fs.open('wx')` — an atomic OS primitive that works on POSIX and NTFS. Only one process can hold this file at a time. All other processes spin (with linear back-off, max 20 retries) until the holder removes it. Stale locks (dead PID or age > 10 s) are automatically removed, including on extension startup via `clearStaleLockOnStartup()`.
+
+2. **Inner — per-file in-process promise queue** (`markdownStore.ts`): `withFileLock(filePath, fn)` chains a `Promise<void>` per file path. This serialises concurrent async calls within the same extension host process (e.g. `storeMemory` + background cleanup hitting the same category file).
+
+Callers outside `markdownStore.ts` never interact with either lock directly. The combined wrapper `withMemoryWriteLock(filePath, fn)` is the only entry point used by `appendMemory`, `upsertMemory`, `deleteMemory`, and `migrateFiles`.
+
+See [ADR 0018](decisions.md#0018--two-tier-write-locking-for-memory-files) for the full decision record.
 
 ### Centralised LM Access
 
@@ -99,7 +107,7 @@ This extension uses:
 - `vscode.lm.selectChatModels` — to select a Copilot model for redundancy checks and gap analysis
 - `vscode.lm.onDidChangeChatModels` — to refresh the status bar when available models change
 
-These APIs require **VS Code 1.99+** (or any Open VSX-compatible editor that implements the VS Code LM Tool API at the same version level). Editors that do not implement `vscode.lm.registerTool` will install the extension but the memory tools will not be available in chat.
+These APIs require **VS Code 1.99+**. The extension publishes to Open VSX; the memory tools function in any editor that implements the VS Code LM Tool API. A separate MCP-based implementation for additional editors is planned (see [ADR 0017](decisions.md#0017--additional-editor-support-via-mcp)).
 
 ## Future: JetBrains Support