@amaster.ai/pi-memory 0.1.2-beta.11

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,129 @@
+# @amaster.ai/pi-memory
+
+Persistent curated memory for pi agents — `MEMORY.md` (the agent's own notes) and `USER.md` (what the agent knows about the user). Both are loaded from disk at session start, **frozen**, and injected into the system prompt for the entire session. Mid-session writes are durable on disk but do **not** mutate the system prompt — this preserves prefix-cache stability.
+
+Modeled after hermes' default `MemoryStore` mechanism (no provider/manager abstraction).
+
+## Storage
+
+- Location: `<agentDir>/memories/MEMORY.md` and `<agentDir>/memories/USER.md`
+- Entries separated by `\n§\n`
+- Atomic writes via temp-file + rename
+- Read-modify-write protected by `proper-lockfile`
+- **Drift detection**: if the on-disk file contains content that wouldn't round-trip through the parser/serializer (or any single entry exceeds the per-store char limit), the mutation is refused and a `.bak.<unix-ts>` snapshot is taken for the user to recover from.
+
+## Safety
+
+Every write — and every system-prompt snapshot build — runs the content through the bundled `threat-patterns` scanner at the `strict` scope. Patterns cover prompt injection, role hijack, C2 framework names, exfiltration, persistence (SSH backdoor, agent-config edits), and invisible unicode.
+
+| Action               | On match                                                                                                  |
+|----------------------|-----------------------------------------------------------------------------------------------------------|
+| `memory_add` / `memory_replace` | Reject with the matched pattern id; live state and disk unchanged.                              |
+| Snapshot build (load) | Replace the entry with `[BLOCKED: <filename> entry contained threat pattern(s): <ids>...]`. The poisoned content **never** enters the system prompt. Live state keeps the original so `memory_read` / `memory_remove` can recover. |
+
+## Tools
+
+Four LLM-callable tools (separate, not action-multiplexed):
+
+| Tool             | Purpose                                                                  |
+|------------------|--------------------------------------------------------------------------|
+| `memory_add`     | Append a new entry. Rejects empty / duplicate / over-limit / threat content. |
+| `memory_replace` | Update an existing entry by short unique substring (`oldText`).          |
+| `memory_remove`  | Delete an entry by short unique substring (`oldText`).                   |
+| `memory_read`    | Return live entries, count, and `<percent>% — <chars>/<limit>` usage string. |
+
+`target` is `'memory'` (the agent's own notes) or `'user'` (user profile facts).
+
+## Defaults
+
+| Store    | Char limit |
+|----------|------------|
+| MEMORY   | 2200       |
+| USER     | 1375       |
+
+These are total chars after `§`-joining all entries. The limit is enforced at write time, and at load time as a drift signal (single-entry overflow).
+
+## Integration Modes
+
+### Mode 1: Extension auto-discovery (standalone / CLI)
+
+When installed as a dependency with the `pi.extensions` field declared in `package.json`, the runtime auto-discovers and loads the extension. The extension creates its own `MemoryStore` with file-based storage at `<agentDir>/memories/` — fully self-contained.
+
+```
+pi.extensions → session_start → load MEMORY.md/USER.md → freeze snapshot → register tools
+              → before_agent_start → append snapshot to systemPrompt
+              → session_shutdown → release
+```
+
+- **Storage**: `<agentDir>/memories/MEMORY.md` and `<agentDir>/memories/USER.md`
+- **Lifecycle**: load on `session_start`, snapshot held until `session_shutdown`
+- **Status command**: `/pi-memory-status` shows entry counts per file
+- **LLM tools**: `memory_add`, `memory_replace`, `memory_remove`, `memory_read`
+
+Configure via the `pi-memory` settings key:
+
+```json
+{
+  "pi-memory": {
+    "dataDir": "/custom/memory/path",
+    "memoryCharLimit": 4000,
+    "userCharLimit": 2000
+  }
+}
+```
+
+### Mode 2: Dependency import (host-controlled)
+
+When the host process owns the `MemoryStore` (e.g. shared across agents, test fixtures, custom storage path), construct the store yourself and register tools directly:
+
+```ts
+import { MemoryStore, createMemoryTools } from "@amaster.ai/pi-memory";
+
+const store = new MemoryStore({
+  dir: "/var/lib/pi/agent-42/memories",
+  memoryCharLimit: 4000,
+});
+await store.loadFromDisk();
+
+// ToolDefinition[] — wire into your tool registry directly
+const tools = createMemoryTools(store);
+
+// System prompt fragment (frozen at loadFromDisk; safe to use repeatedly)
+const promptBlock = store.formatAllForSystemPrompt();
+```
+
+You can also pass a pre-built store into the extension via `injectedConfig` to keep the extension lifecycle but use your own storage:
+
+```ts
+import memoryExtension from "@amaster.ai/pi-memory";
+
+memoryExtension(pi, { store });
+```
+
+## Drift recovery
+
+If `memory_add` / `memory_replace` / `memory_remove` returns `success: false` with `driftBackup: ".../MEMORY.md.bak.<ts>"`, the on-disk file no longer round-trips through the parser. This usually means a patch tool / shell append / manual edit / concurrent session wrote raw content that broke the `§`-delimited structure.
+
+To recover:
+
+1. Open the `.bak.<ts>` snapshot and identify content not yet captured as clean entries.
+2. Add each missing entry via `memory_add`.
+3. Either delete the original `MEMORY.md` (the next add will recreate it) or rewrite it as a clean `§`-delimited list.
+
+The drift guard exists to prevent silent data loss — never bypass it by deleting `.bak.<ts>` snapshots blindly.
+
+## Frozen snapshot
+
+`loadFromDisk()` captures the system-prompt block once; subsequent `add` / `replace` / `remove` calls update **live state** but not the snapshot. Why:
+
+- The system prompt is the prefix-cache key for every model call. Mutating it mid-session invalidates the entire prefix.
+- Tool responses always reflect live state, so the model still sees its own writes — just via tool-result tail, not system-prompt head.
+- The snapshot picks up changes on the **next** `loadFromDisk()` (typically the next session start).
+
+## Lifecycle reference
+
+| Hook                  | Behavior                                                                  |
+|-----------------------|---------------------------------------------------------------------------|
+| `session_start`       | Resolve `dataDir`, build `MemoryStore`, `loadFromDisk()`, capture snapshot, register 4 tools, set status `memory: loaded`/`memory: empty`. |
+| `before_agent_start`  | Append snapshot to assembled `systemPrompt` (no-op when empty).           |
+| `session_shutdown`    | Drop store + snapshot references.                                         |

package/dist/extension.d.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { MemoryStore } from './store.js';
+export type PiMemoryExtensionConfig = {
+    /** Directory containing MEMORY.md / USER.md. Default: `<agentDir>/memories`. */
+    dataDir?: string;
+    /** Char limit for MEMORY.md. Default 2200. */
+    memoryCharLimit?: number;
+    /** Char limit for USER.md. Default 1375. */
+    userCharLimit?: number;
+    /** Pre-built store (host-controlled mode). */
+    store?: MemoryStore;
+};
+export default function memoryExtension(pi: ExtensionAPI, injectedConfig?: PiMemoryExtensionConfig): void;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAoBzC,MAAM,MAAM,uBAAuB,GAAG;IACpC,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AA+BF,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,EAAE,EAAE,YAAY,EAChB,cAAc,CAAC,EAAE,uBAAuB,GACvC,IAAI,CA8DN"}

package/dist/extension.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import { loadPiSettings, resolveAgentDir } from '@amaster.ai/pi-shared/settings';
+import { MemoryStore } from './store.js';
+import { createMemoryTools } from './tools.js';
+const SETTINGS_KEY = 'pi-memory';
+const STATUS_KEY = 'pi-memory';
+const MEMORY_GUIDANCE = [
+    '## Memory Guidance',
+    '',
+    'You have persistent memory across sessions via the memory_add / memory_replace / memory_remove / memory_read tools.',
+    'Save durable facts: user preferences, environment details, tool quirks, and stable conventions.',
+    'Memory is injected into every turn, so keep it compact and focused on facts that will still matter later.',
+    '',
+    'Prioritize what reduces future user steering — the most valuable memory is one that prevents the user from having to correct or remind you again. User preferences and recurring corrections matter more than procedural task details.',
+    '',
+    "Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO state. Specifically: do not record PR numbers, issue numbers, commit SHAs, 'fixed bug X', 'submitted PR Y', 'Phase N done', file counts, or any artifact that will be stale in 7 days. If a fact will be stale in a week, it does not belong in memory.",
+    '',
+    "Write memories as declarative facts, not instructions to yourself. 'User prefers concise responses' ✓ — 'Always respond concisely' ✗. 'Project uses pytest with xdist' ✓ — 'Run tests with pytest -n 4' ✗. Imperative phrasing gets re-read as a directive in later sessions and can cause repeated work or override the user's current request.",
+].join('\n');
+function resolveConfig(raw) {
+    const resolved = {
+        dataDir: raw?.dataDir?.trim() || path.join(resolveAgentDir(), 'memories'),
+    };
+    if (raw?.memoryCharLimit !== undefined)
+        resolved.memoryCharLimit = raw.memoryCharLimit;
+    if (raw?.userCharLimit !== undefined)
+        resolved.userCharLimit = raw.userCharLimit;
+    if (raw?.store)
+        resolved.store = raw.store;
+    return resolved;
+}
+function loadSettings(cwd) {
+    try {
+        const config = loadPiSettings(SETTINGS_KEY, {
+            cwd,
+            agentDir: resolveAgentDir(),
+        });
+        return Object.keys(config).length > 0 ? config : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default function memoryExtension(pi, injectedConfig) {
+    let store;
+    let snapshot = '';
+    pi.on('session_start', async (_event, ctx) => {
+        const fileConfig = loadSettings(ctx.cwd);
+        const config = resolveConfig({ ...fileConfig, ...injectedConfig });
+        try {
+            if (config.store) {
+                store = config.store;
+            }
+            else {
+                const opts = { dir: config.dataDir };
+                if (config.memoryCharLimit !== undefined)
+                    opts.memoryCharLimit = config.memoryCharLimit;
+                if (config.userCharLimit !== undefined)
+                    opts.userCharLimit = config.userCharLimit;
+                store = new MemoryStore(opts);
+            }
+            await store.loadFromDisk();
+            snapshot = store.formatAllForSystemPrompt();
+            ctx.ui.setStatus(STATUS_KEY, snapshot ? 'memory: loaded' : 'memory: empty');
+            for (const tool of createMemoryTools(store)) {
+                pi.registerTool(tool);
+            }
+        }
+        catch (err) {
+            ctx.ui.setStatus(STATUS_KEY, 'memory: unavailable');
+            // Surface as a notification only — registration failure shouldn't crash the session.
+            ctx.ui.notify(`pi-memory failed to initialize: ${err instanceof Error ? err.message : String(err)}`, 'error');
+        }
+    });
+    pi.on('before_agent_start', async (event) => {
+        const block = snapshot ? `${MEMORY_GUIDANCE}\n\n${snapshot}` : MEMORY_GUIDANCE;
+        return {
+            systemPrompt: event.systemPrompt ? `${event.systemPrompt}\n\n${block}` : block,
+        };
+    });
+    pi.on('session_shutdown', async () => {
+        store = undefined;
+        snapshot = '';
+    });
+    pi.registerCommand('pi-memory-status', {
+        description: 'Show pi-memory status (entry counts and char usage).',
+        handler: async (_args, ctx) => {
+            if (!store) {
+                ctx.ui.notify('pi-memory is not loaded.', 'warning');
+                return;
+            }
+            const memEntries = store.getEntries('memory');
+            const userEntries = store.getEntries('user');
+            ctx.ui.notify(`MEMORY.md: ${memEntries.length} entries\nUSER.md: ${userEntries.length} entries`, 'info');
+        },
+    });
+}
+//# sourceMappingURL=extension.js.map

package/dist/extension.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { default } from './extension.js';
+export type { MemoryDriftError, MemoryErrorResult, MemoryResult, MemoryStoreOptions, MemorySuccessResult, MemoryTarget, } from './store.js';
+export { ENTRY_DELIMITER, MemoryStore } from './store.js';
+export { firstThreatMessage, INVISIBLE_CHARS, scanForThreats } from './threat-patterns.js';
+export { createMemoryTools } from './tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { default } from './extension.js';
+export { ENTRY_DELIMITER, MemoryStore } from './store.js';
+export { firstThreatMessage, INVISIBLE_CHARS, scanForThreats } from './threat-patterns.js';
+export { createMemoryTools } from './tools.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AASzC,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,91 @@
+export declare const ENTRY_DELIMITER = "\n\u00A7\n";
+export type MemoryTarget = 'memory' | 'user';
+export type MemoryStoreOptions = {
+    /** Directory where MEMORY.md and USER.md live. */
+    dir: string;
+    /** Char limit for MEMORY.md. Default 2200. */
+    memoryCharLimit?: number;
+    /** Char limit for USER.md. Default 1375. */
+    userCharLimit?: number;
+};
+export type MemorySuccessResult = {
+    success: true;
+    target: MemoryTarget;
+    entries: string[];
+    usage: string;
+    entryCount: number;
+    message?: string;
+};
+export type MemoryDriftError = {
+    success: false;
+    error: string;
+    driftBackup: string;
+    remediation: string;
+};
+export type MemoryErrorResult = {
+    success: false;
+    error: string;
+    matches?: string[];
+    currentEntries?: string[];
+    usage?: string;
+};
+export type MemoryResult = MemorySuccessResult | MemoryDriftError | MemoryErrorResult;
+/**
+ * Bounded curated memory with file persistence.
+ *
+ * Two parallel states:
+ *  - `_systemPromptSnapshot`: frozen at `loadFromDisk()`, used for system
+ *    prompt injection. Never mutated mid-session — keeps prefix cache stable.
+ *  - `memoryEntries` / `userEntries`: live state, mutated by tool calls,
+ *    persisted to disk. Tool responses always reflect this live state.
+ */
+export declare class MemoryStore {
+    readonly dir: string;
+    readonly memoryCharLimit: number;
+    readonly userCharLimit: number;
+    private memoryEntries;
+    private userEntries;
+    private systemPromptSnapshot;
+    private loaded;
+    constructor(opts: MemoryStoreOptions);
+    /**
+     * Load entries from MEMORY.md and USER.md, capture system prompt snapshot.
+     *
+     * Each entry is scanned for injection / promptware patterns at strict
+     * scope; ANY match replaces the entry text in the snapshot with a
+     * `[BLOCKED: …]` placeholder so a poisoned-on-disk file (supply chain,
+     * compromised tool, sister-session write) cannot enter the system
+     * prompt. Live state keeps the original so the user can inspect and
+     * remove via `memory_read` / `memory_remove`.
+     */
+    loadFromDisk(): Promise<void>;
+    /** Return frozen snapshot for system prompt injection. Empty string if no entries. */
+    formatForSystemPrompt(target: MemoryTarget): string;
+    /** Combined memory + user snapshot block, with a blank line between them. */
+    formatAllForSystemPrompt(): string;
+    /** Live entries, not the frozen snapshot. */
+    getEntries(target: MemoryTarget): string[];
+    add(target: MemoryTarget, content: string): Promise<MemoryResult>;
+    replace(target: MemoryTarget, oldText: string, newContent: string): Promise<MemoryResult>;
+    remove(target: MemoryTarget, oldText: string): Promise<MemoryResult>;
+    read(target: MemoryTarget): Promise<MemorySuccessResult>;
+    private pathFor;
+    private entriesFor;
+    private setEntries;
+    private charLimit;
+    private charCount;
+    private successResponse;
+    private renderBlock;
+    private saveToDisk;
+    /**
+     * Re-read entries from disk. Returns backup-path string when external
+     * drift was detected (the on-disk file contains content that wouldn't
+     * round-trip through the parser/serializer, OR an entry larger than the
+     * store's char limit). Caller must abort the mutation when drift is
+     * detected — flushing would discard the un-roundtrippable content.
+     */
+    private reloadTarget;
+    private detectExternalDrift;
+    private withFileLock;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,eAAe,eAAU,CAAC;AAEvC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE7C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAetF;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,oBAAoB,CAA0D;IACtF,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,kBAAkB;IAMpC;;;;;;;;;OASG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAWnC,sFAAsF;IACtF,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAInD,6EAA6E;IAC7E,wBAAwB,IAAI,MAAM;IAOlC,6CAA6C;IAC7C,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE;IAIpC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA0CjE,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA2DzF,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCpE,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS9D,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,WAAW;YAWL,UAAU;IAKxB;;;;;;OAMG;YACW,YAAY;YAOZ,mBAAmB;YAgCnB,YAAY;CA4B3B"}