quilltap 4.11.0-dev.11 → 4.11.0-dev.110

package/README.md

@@ -333,7 +333,7 @@ A character vault's **keystone files** — `properties.json`, the five required
 
 ## Memories
 
-`quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable. All verbs open the main encrypted DB read-only; the two that change anything (`maintain`, `validate --repair --write`) ask the running server to do the work.
+`quilltap memories` exposes the same Commonplace Book that each character carries — searchable, sortable, graphable. All verbs open the main encrypted DB read-only; the three that change anything (`maintain`, `validate --repair --write`, `keystone --write`) ask the running server to do the work.
 
 ```bash
 quilltap memories ls                                                   # All holders, default sort: reinforcedImportance DESC
@@ -346,15 +346,16 @@ quilltap memories tree <id|prefix> [--depth N] [--max-nodes N]         # ASCII w
 quilltap memories status [--character <name|id>] [--port <n>]          # Per-holder rollup, maintenance ledger + dangling-edge check
 quilltap memories validate [--character <name|id>] [--list]            # Graph health check; exit 1 if any dangling link remains
 quilltap memories validate --repair [--write]                          # Rehearse (or, with --write, apply) the server's graph repair
+quilltap memories keystone <id|prefix> [--off] [--write]               # Rehearse (or, with --write, apply) marking a keystone — a standing fact
 quilltap memories grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
 quilltap memories maintain --character Ariadne --dry-run               # Rehearse every maintenance phase (server required)
 quilltap memories maintain --character Ariadne --phases consolidate    # Queue a consolidation-only maintenance job
 quilltap memories maintain --character all [--phases demote,retire]    # Queue maintenance for every character
 ```
 
-Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source` (AUTO / MANUAL / CONSOLIDATED), `--tier` (hot / cold; both by default, cold rows are starred in the `src` column), `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` / `--reverse` to flip it, `--limit N` (default 50) and `--full-titles` to stop chat titles being truncated to 32 characters) apply to `ls`, `find`, and `grep`. `grep -l` / `--paths-only` prints only the IDs of matching memories, one per line. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. `validate` is `status`'s terse twin — read-only; it counts dangling `relatedMemoryIds` edges, dangling `consolidatedFrom` members (digests naming notes that are gone), dangling `supersededById` pointers, and rows with no embedding. It exits 1 if any dangling link remains (a missing embedding only warns), and `--list` prints the offending IDs. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains, now with `--tier hot|cold` (rows with no tier count as hot).
+Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source` (AUTO / MANUAL / CONSOLIDATED), `--tier` (hot / cold; both by default, cold rows are starred in the `src` column), `--keystone` (keystones only; a keystone's summary is prefixed `◆` in tables, and `show` prints a `Keystone:` line), `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` / `--reverse` to flip it, `--limit N` (default 50) and `--full-titles` to stop chat titles being truncated to 32 characters) apply to `ls`, `find`, and `grep`. `grep -l` / `--paths-only` prints only the IDs of matching memories, one per line. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. `validate` is `status`'s terse twin — read-only; it counts dangling `relatedMemoryIds` edges, dangling `consolidatedFrom` members (digests naming notes that are gone), dangling `supersededById` pointers, and rows with no embedding. It exits 1 if any dangling link remains (a missing embedding only warns), and `--list` prints the offending IDs. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains, now with `--tier hot|cold` (rows with no tier count as hot).
 
-Verbs that call the server (`grep --semantic`, `status`'s ledger, `maintain`, `validate --repair`) take `--port`; without it they use the port recorded in the `--instance` / `--data-dir` instance's lock, else 3000.
+Verbs that call the server (`grep --semantic`, `status`'s ledger, `maintain`, `validate --repair`, `keystone --write`) take `--port`; without it they use the port recorded in the `--instance` / `--data-dir` instance's lock, else 3000.
 
 `maintain` runs the memory maintenance job by hand: `fold-near-duplicates`, `consolidate`, `demote`, `retire`, `mirror`, always in that order. `--character <name|id|all>` is required (`all` is every character you own); `--phases a,b,…` picks a subset (checked by the server, which answers an unknown name with a 400; naming `consolidate` brings `mirror` along, since the Commonplace mirror follows consolidation). The CLI resolves the character locally and asks the running server — the model, the embeddings and the only database writer live there. With `--dry-run` the server rehearses the run and writes nothing: the CLI prints each phase's status (ran / skipped, and why), then the fold groups, the consolidation clusters (member notes, proposed digests, standalones, contradictions, run stats), the demotion arithmetic (cap, hot total, demotable, protected, excess, demoted), the retire count and the mirror subjects. A dry run over `all` gives one table row per character and may not include `consolidate` (each would call the model). Without `--dry-run` the server queues one `MEMORY_MAINTENANCE` job per character and the CLI prints the job ids; manual runs ignore the master `enabled` switches. `--max N` caps clusters consolidated (`maxClustersPerRun`, 1–1000; a dry run defaults to 10, at most 40), `--threshold 0..1` overrides the cluster similarity (neural embedding profiles), `--cap N` overrides the hot-row cap for demotion (100–100000). `--json` prints the raw API payload. There is no `consolidate` verb any more: use `maintain --phases consolidate`.
 
@@ -391,7 +392,7 @@ Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-
 
 Tuning and comparable runs:
 
-- `--tuning '<json>'` / `--tuning-file <path>` — retuning constants for the new path only (the old path stays the reference): `boostGateAbs`, `boostGateMargin`, `boostGateRamp` (relevance gate on boosts), `boostCap`, `freshBypassesGate`, `windowBypassesGate`, `multipliers` (`{ "freshEvent24h": 1.3, … }`), `specificAnchors`, `anchorMinHits`, `anchorOrder`, `backgroundReserve`. Unknown keys are rejected. The header's `Tuning` line shows what is active.
+- `--tuning '<json>'` / `--tuning-file <path>` — retuning constants for the new path only (the old path stays the reference): `boostGateAbs`, `boostGateMargin`, `boostGateRamp` (relevance gate on boosts), `boostCap`, `freshBypassesGate`, `windowBypassesGate`, `multipliers` (`{ "freshEvent24h": 1.3, … }`), `specificAnchors`, `anchorMinHits`, `anchorOrder`, `backgroundReserve`, `innerCircleShare` (share of the frozen archive the group inner circle may take, default `0.333…`), `innerCircleAllowance` (digests per circle member by tier, tightest group first, default `[3, 2, 1]`). Unknown keys are rejected. The header's `Tuning` line shows what is active.
 - `--signals-from <replay.json>` — reuse the signals saved in an earlier `--json` replay of the same chat and turn. The distillation is a cheap-LLM call and words the same turn differently each time, so runs you mean to compare should share it.
 - `--as-of` — search only memories created before the turn's opening message, with weights decayed to the turn's own clock: the corpus as it stood then. The header's `Harness` line shows the cutoff and how many later memories were left out.
 

package/bin/quilltap.js

@@ -1045,7 +1045,7 @@ async function dbCommand(args) {
     } else if (countTable) {
       const row = db.prepare(`SELECT count(*) as count FROM "${countTable}"`).get();
       if (asJson) console.log(JSON.stringify({ table: countTable, count: row.count }, null, 2));
-      else console.log(row.count);
+      else console.log(String(row.count));
     } else if (sql) {
       const stmt = db.prepare(sql);
       if (stmt.reader) {

package/lib/__tests__/platform-paths.test.js

@@ -0,0 +1,62 @@
+/**
+ * Platform default instance root, including the Docker case.
+ *
+ * The bug this guards: inside the Docker image `quilltap db --lock-status`
+ * fell through to `~/.quilltap` (a home directory the image never creates),
+ * reported "No instance lock found" while the server held one, and
+ * `db --tables` reported a missing database.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+const { getDefaultBaseDir, isDockerContainer, DOCKER_BASE_DIR } = require('../platform-paths');
+const { resolveDataDir } = require('../db-helpers');
+
+const savedEnv = { ...process.env };
+
+afterEach(() => {
+  process.env = { ...savedEnv };
+});
+
+describe('platform default instance root', () => {
+  it('is /app/quilltap inside the Docker image', () => {
+    process.env.DOCKER_CONTAINER = 'true';
+    expect(isDockerContainer()).toBe(true);
+    expect(getDefaultBaseDir()).toBe(DOCKER_BASE_DIR);
+  });
+
+  it('is the per-OS location outside a container', () => {
+    delete process.env.DOCKER_CONTAINER;
+    if (isDockerContainer()) return; // the suite itself is running in a container
+    const expected = process.platform === 'darwin'
+      ? path.join(os.homedir(), 'Library', 'Application Support', 'Quilltap')
+      : process.platform === 'win32'
+        ? path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Quilltap')
+        : path.join(os.homedir(), '.quilltap');
+    expect(getDefaultBaseDir()).toBe(expected);
+  });
+});
+
+describe('resolveDataDir', () => {
+  it('defaults to the Docker data directory inside the image', () => {
+    process.env.DOCKER_CONTAINER = 'true';
+    delete process.env.QUILLTAP_DATA_DIR;
+    expect(resolveDataDir()).toBe('/app/quilltap/data');
+  });
+
+  it('still lets QUILLTAP_DATA_DIR win inside the image', () => {
+    process.env.DOCKER_CONTAINER = 'true';
+    process.env.QUILLTAP_DATA_DIR = '/elsewhere';
+    expect(resolveDataDir()).toBe(path.join('/elsewhere', 'data'));
+  });
+
+  it('still lets an explicit override win', () => {
+    process.env.DOCKER_CONTAINER = 'true';
+    expect(resolveDataDir('/explicit')).toBe(path.join('/explicit', 'data'));
+  });
+});

package/lib/completion/bash.template

@@ -321,12 +321,12 @@ _quilltap_complete() {
       fi
       ;;
     memories)
-      local mem_verbs="ls find grep show tree status validate maintain"
+      local mem_verbs="ls find grep show tree status validate keystone maintain"
       local mem_flags="--character --about --source --tier --chat --project --since --until \
         --min-importance --min-reinforced --has-embedding --no-embedding \
         --sort -r --reverse --limit --full-titles --in --no-related --list \
         --ignore-case -i --paths-only -l --max --context --depth --max-nodes \
-        --semantic --top --threshold --dry-run --phases --cap --repair --write \
+        --semantic --top --threshold --dry-run --phases --cap --repair --write --keystone --off \
         --instance --data-dir --passphrase -p --port --json --help"
       if [[ -z "$subverb" ]]; then
         if [[ "$cur" == -* ]]; then

package/lib/completion/fish.template

@@ -273,6 +273,7 @@ complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'show' -d '
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'tree' -d 'Graph walk'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'status' -d 'Memory status'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'validate' -d 'Health check'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'keystone' -d 'Mark or unmark a keystone'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'maintain' -d 'Run memory maintenance'
 
 # memories flags
@@ -284,7 +285,9 @@ complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'dry-run' -d '
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'phases' -d 'Maintain: comma-separated phases' -x -a 'fold-near-duplicates consolidate demote retire mirror'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'cap' -d 'Maintain: hot-row cap for demotion' -x
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'repair' -d 'Validate: repair the graph on the running server'
-complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'write' -d 'Validate --repair: apply the repair'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'write' -d 'Validate --repair / keystone: apply the change'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'keystone' -d 'Only keystones'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'off' -d 'Keystone: unmark instead of mark'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'chat' -d 'Chat id or title' -x
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'project' -d 'Project name or id' -x
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'since' -d 'Since timestamp' -x

package/lib/completion/zsh.template

@@ -539,6 +539,7 @@ _quilltap_memories() {
     'tree:ASCII walk of graph'
     'status:Per-character rollup'
     'validate:Health check'
+    'keystone:Mark or unmark a keystone (standing fact) via the running server'
     'maintain:Run memory maintenance (fold, consolidate, demote, retire, mirror)'
   )
 
@@ -556,7 +557,9 @@ _quilltap_memories() {
     '--phases[Maintain: comma-separated phases]:phases:_sequence compadd - fold-near-duplicates consolidate demote retire mirror'
     '--cap[Maintain: hot-row cap for demotion]:n:'
     '--repair[Validate: repair the graph on the running server (dry run without --write)]'
-    '--write[Validate --repair: apply the repair]'
+    '--write[Validate --repair / keystone: apply the change]'
+    '--keystone[Only keystones]'
+    '--off[Keystone: unmark instead of mark]'
     '--chat[Chat id or title]:chat:'
     '--project[Project name or id]:project:'
     '--since[Since timestamp]:date:'

package/lib/db-commands.js

@@ -31,6 +31,7 @@ const DB_DOMAINS = {
   },
   logs: {
     'LLM logs': ['llm_logs'],
+    'Log entries': ['log_entries'],
   },
   mount: {
     'Document mount index': [

package/lib/db-helpers.js

@@ -15,14 +15,11 @@ function resolveDataDir(overrideDir) {
       : overrideDir;
     return path.join(resolved, 'data');
   }
-  const os = require('os');
   if (process.env.QUILLTAP_DATA_DIR) {
     return path.join(process.env.QUILLTAP_DATA_DIR, 'data');
   }
-  const home = os.homedir();
-  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Quilltap', 'data');
-  if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Quilltap', 'data');
-  return path.join(home, '.quilltap', 'data');
+  const { getDefaultBaseDir } = require('./platform-paths');
+  return path.join(getDefaultBaseDir(), 'data');
 }
 
 // Resolve the data dir + database passphrase a subcommand should use, given

package/lib/lock-helpers.js

@@ -206,10 +206,7 @@ let exitHandlersRegistered = false;
 function detectEnvironmentType() {
   if (process.versions && process.versions.electron) return 'electron';
   if (process.env.ELECTRON_DEV) return 'electron';
-  if (process.env.DOCKER_CONTAINER === 'true') return 'docker';
-  try {
-    if (fs.existsSync('/.dockerenv')) return 'docker';
-  } catch { /* not Docker */ }
+  if (require('./platform-paths').isDockerContainer()) return 'docker';
   return 'local';
 }
 

package/lib/memories-commands.js

@@ -18,7 +18,7 @@ const {
   memoryColumns,
 } = require('./graph-integrity');
 const { cmdMaintain } = require('./memories-maintain-command');
-const { postMemoriesAction, resolveMemoriesServerPort } = require('./memories-server');
+const { postMemoriesAction, putMemory, resolveMemoriesServerPort } = require('./memories-server');
 
 // ---------- colour & marker helpers ----------
 
@@ -152,6 +152,8 @@ function parseFlags(args) {
       case '--list': flags.list = true; break;
       case '--repair': flags.repair = true; break;
       case '--write': flags.write = true; break;
+      case '--keystone': flags.keystone = true; break;
+      case '--off': flags.off = true; break;
 
       case '--phases': flags.phases = args[++i] || ''; break;
       case '--cap': {
@@ -257,6 +259,11 @@ function buildWhereClause(db, flags, openMounts = null) {
     params.push(s);
   }
 
+  if (flags.keystone) {
+    // Instances that haven't run add-memory-keystone-v1 have no keystones.
+    clauses.push(hasMemoryColumn(db, 'keystone') ? 'm.keystone = 1' : '0');
+  }
+
   if (flags.tier) {
     const t = String(flags.tier).toLowerCase();
     if (t !== 'hot' && t !== 'cold') {
@@ -386,17 +393,23 @@ const SELECT_BASE_TEMPLATE = `
   LEFT JOIN projects ON projects.id = m.projectId
 `;
 
-// Instances that haven't yet run add-memory-tiers-v1 lack the tier columns;
-// substitute constants so the CLI still reads them (rows read as hot).
-function selectBase(db) {
-  let hasTier = false;
+function hasMemoryColumn(db, name) {
   try {
-    hasTier = db.prepare("PRAGMA table_info('memories')").all().some((c) => c.name === 'tier');
-  } catch { /* fall through: treat as legacy */ }
-  const cols = hasTier
+    return db.prepare("PRAGMA table_info('memories')").all().some((c) => c.name === name);
+  } catch {
+    return false; // treat as legacy
+  }
+}
+
+// Instances that haven't yet run add-memory-tiers-v1 lack the tier columns (and
+// those before add-memory-keystone-v1 the keystone column); substitute
+// constants so the CLI still reads them (rows read as hot, not keystones).
+function selectBase(db) {
+  const tierCols = hasMemoryColumn(db, 'tier')
     ? 'm.tier, m.supersededById, m.consolidatedFrom, m.consolidatedAt,'
     : "'hot' AS tier, NULL AS supersededById, '[]' AS consolidatedFrom, NULL AS consolidatedAt,";
-  return SELECT_BASE_TEMPLATE.replace('__TIER_COLUMNS__', cols);
+  const keystoneCol = hasMemoryColumn(db, 'keystone') ? 'm.keystone,' : '0 AS keystone,';
+  return SELECT_BASE_TEMPLATE.replace('__TIER_COLUMNS__', `${tierCols} ${keystoneCol}`);
 }
 
 
@@ -499,6 +512,7 @@ function rowToJson(row) {
     supersededById: row.supersededById || null,
     consolidatedFrom: (() => { try { return JSON.parse(row.consolidatedFrom || '[]'); } catch { return []; } })(),
     consolidatedAt: row.consolidatedAt || null,
+    keystone: Number(row.keystone) === 1,
     importance: row.importance,
     reinforcedImportance: row.reinforcedImportance,
     reinforcementCount: row.reinforcementCount,
@@ -546,7 +560,8 @@ function renderTable(rows, { showHolder, impField, fullTitles }) {
     const chat = truncate(chatLabel(row, fullTitles), fullTitles ? 24 : 32).padEnd(fullTitles ? 24 : 32);
     const links = String(linkCount(row)).padStart(5);
     const emb = row.hasEmbedding ? 'Y' : '-';
-    const summary = truncate(row.summary || '', sumW);
+    // A keystone's line is marked ◆ (a standing fact; never folded or demoted).
+    const summary = (Number(row.keystone) === 1 ? '◆ ' : '') + truncate(row.summary || '', sumW);
 
     const cells = [
       showHolder ? truncate(row.holderName || '(?)', 14).padEnd(14) : null,
@@ -937,6 +952,7 @@ function renderShowText(row, graph, depth) {
   console.log(`  About:         ${aboutName}${row.aboutCharacterId && row.aboutCharacterId !== row.characterId ? `    (${shortId(row.aboutCharacterId)})` : ''}`);
   console.log(`  Source:        ${row.source || '(?)'}`);
   console.log(`  Tier:          ${row.tier || 'hot'}${row.supersededById ? `    (superseded by ${shortId(row.supersededById)})` : ''}`);
+  console.log(`  Keystone:      ${Number(row.keystone) === 1 ? 'yes (standing fact)' : 'no'}`);
   const reinf = row.reinforcedImportance != null ? Number(row.reinforcedImportance).toFixed(2) : '?';
   const baseImp = row.importance != null ? Number(row.importance).toFixed(2) : '?';
   console.log(`  Importance:    ${reinf} (reinforced from ${baseImp}, count: ${row.reinforcementCount ?? 0})`);
@@ -1507,6 +1523,51 @@ function renderRepairText(report) {
   }
 }
 
+// ---------- keystone ----------
+
+/**
+ * Mark or unmark a keystone. The id resolves locally (read-only); the change
+ * itself goes to the running server's memory PUT, through the edit chokepoint
+ * that enforces the per-subject limit and invalidates the frozen archive.
+ */
+async function cmdKeystone(flags, positional) {
+  const idArg = positional[0];
+  if (!idArg) {
+    throw new Error('memories keystone: missing <id>. Usage: quilltap memories keystone <id|prefix> [--off] [--write]');
+  }
+  const want = !flags.off;
+  const { db } = await openDb(flags);
+  let row;
+  try {
+    const id = resolveMemoryId(db, idArg);
+    row = db.prepare(`${selectBase(db)} WHERE m.id = ?`).get(id);
+    if (!row) throw new Error(`Memory ${id} not found`);
+  } finally {
+    db.close();
+  }
+  const is = Number(row.keystone) === 1;
+  const label = `${shortId(row.id)} (${truncate(row.summary || '', 60)})`;
+  if (is === want) {
+    const msg = `${label} is ${want ? 'already' : 'not'} a keystone; nothing to do.`;
+    if (flags.json) renderJson({ id: row.id, keystone: is, changed: false }); else console.log(msg);
+    return;
+  }
+  if (!flags.write) {
+    const msg = `Would ${want ? 'mark' : 'unmark'} ${label} as a keystone. Re-run with --write to apply.`;
+    if (flags.json) renderJson({ id: row.id, keystone: is, wouldBe: want, changed: false, dryRun: true }); else console.log(msg);
+    return;
+  }
+  const payload = await putMemory(flags, row.id, { keystone: want }, {
+    why: 'Changing a keystone needs the running server (the only database writer).',
+  });
+  const now = Boolean(payload && payload.memory && payload.memory.keystone);
+  if (flags.json) {
+    renderJson({ id: row.id, keystone: now, changed: now === want });
+  } else {
+    console.log(`${want ? 'Marked' : 'Unmarked'} ${label} as a keystone.`);
+  }
+}
+
 // ---------- help ----------
 
 function printMemoriesHelp() {
@@ -1559,6 +1620,16 @@ Subcommands:
                                              server (the only database
                                              writer, holder of the instance
                                              lock), so the server must be up.
+  keystone <id|prefix> [--off] [--write] [--port N]
+                                             Mark a memory a keystone (a
+                                             standing fact, always recalled in
+                                             full, never folded, consolidated
+                                             or demoted), or unmark it with
+                                             --off. Without --write it only
+                                             says what would change; with
+                                             --write the running server makes
+                                             the change (at most 5 keystones
+                                             per holder and subject).
   maintain --character <name|id|all> [--phases a,b,…] [--dry-run]
            [--max N] [--threshold 0..1] [--cap N] [--port N] [--json]
                                              Run memory maintenance by hand on
@@ -1586,6 +1657,7 @@ Shared filter flags:
   --about <name|id|self|none> Subject (aboutCharacterId).
   --source AUTO|MANUAL|CONSOLIDATED  Restrict by source.
   --tier hot|cold             Restrict by recall tier (default: both).
+  --keystone                  Only keystones (marked ◆ in tables).
   --chat <id|title|none>      Source chat ('none' for manual memories).
   --project <id|name>         Project context.
   --since <date>              ISO date floor on createdAt.
@@ -1617,9 +1689,9 @@ Note: -i is reserved here for 'grep --ignore-case'. Use the long --instance
 form to target a registered instance.
 
 All memories verbs are read-only. They open the main encrypted database
-(quilltap.db) and never write to it. 'maintain' and 'validate --repair' leave
-the writing to the running server; 'validate --repair' changes data only with
---write.
+(quilltap.db) and never write to it. 'maintain', 'keystone' and 'validate
+--repair' leave the writing to the running server; 'keystone' and 'validate
+--repair' change data only with --write.
 
 Examples:
   quilltap memories ls
@@ -1634,6 +1706,9 @@ Examples:
   quilltap memories validate --list
   quilltap memories validate --repair                 # rehearse the repair
   quilltap memories validate --repair --write         # apply it
+  quilltap memories ls --character Friday --keystone
+  quilltap memories keystone abc12345 --write         # mark a standing fact
+  quilltap memories keystone abc12345 --off --write   # unmark it
   quilltap memories maintain --instance Friday --character Friday --dry-run
   quilltap memories maintain --instance Friday --character Friday --phases consolidate --max 100
   quilltap memories maintain --character all --phases demote,retire --dry-run
@@ -1671,8 +1746,11 @@ async function memoriesCommand(args) {
   if (flags.repair && verb !== 'validate') {
     throw new Error('--repair applies only to memories validate.');
   }
-  if (flags.write && !(verb === 'validate' && flags.repair)) {
-    throw new Error('--write applies only to memories validate --repair.');
+  if (flags.write && !(verb === 'validate' && flags.repair) && verb !== 'keystone') {
+    throw new Error('--write applies only to memories validate --repair and memories keystone.');
+  }
+  if (flags.off && verb !== 'keystone') {
+    throw new Error('--off applies only to memories keystone.');
   }
   switch (verb) {
     case 'ls': await cmdLs(flags); break;
@@ -1682,6 +1760,7 @@ async function memoriesCommand(args) {
     case 'tree': await cmdTree(flags, positional); break;
     case 'status': await cmdStatus(flags); break;
     case 'validate': await cmdValidate(flags); break;
+    case 'keystone': await cmdKeystone(flags, positional); break;
     case 'maintain': await cmdMaintain(flags, resolveCharacterIdForServer); break;
     default:
       console.error(`Unknown memories subcommand: ${verb}`);

package/lib/memories-server.js

@@ -3,9 +3,10 @@
 /**
  * The one way a `quilltap memories` verb asks the running server to do what
  * the CLI cannot: anything that calls a model, computes an embedding or
- * writes. The CLI's own database access is read-only; `maintain` and
- * `validate --repair` resolve what they can locally and POST the rest to
- * `/api/v1/memories?action=<action>`.
+ * writes. The CLI's own database access is read-only; `maintain`,
+ * `validate --repair` and `keystone` resolve what they can locally and send
+ * the rest to `/api/v1/memories?action=<action>` (or, for a hand edit, the
+ * memory's own PUT).
  *
  * The port comes from `resolveServerPort` (lock-helpers): an explicit
  * `--port`, else the port recorded in the `--instance` / `--data-dir`
@@ -29,28 +30,20 @@ function resolveMemoriesServerPort(flags, { quiet = false } = {}) {
 }
 
 /**
- * POST `body` to `/api/v1/memories?action=<action>` and return the parsed
- * payload. Throws an Error with a readable message on a connection failure
- * or a non-2xx response.
- *
- * @param {object} flags            parsed memories flags (port / instance / dataDir)
- * @param {string} action           the `?action=` name
- * @param {object} body             JSON request body
- * @param {object} [opts]
- * @param {string} [opts.why]       one line on why the server is needed
- * @param {(msg: string) => void} [opts.announce] called with the URL before the request
- * @param {typeof fetch} [opts.fetchImpl] for tests
+ * Send `body` to a memories API path on the running server and return the
+ * parsed payload. Throws an Error with a readable message on a connection
+ * failure or a non-2xx response.
  */
-async function postMemoriesAction(flags, action, body, opts = {}) {
-  const { why, announce, fetchImpl = fetch } = opts;
+async function requestMemoriesApi(flags, method, path, body, opts = {}) {
+  const { why, announce, fetchImpl = fetch, action } = opts;
   const target = resolveMemoriesServerPort(flags);
-  const url = `http://localhost:${target.port}/api/v1/memories?action=${encodeURIComponent(action)}`;
+  const url = `http://localhost:${target.port}${path}`;
   if (announce) announce(url);
 
   let res;
   try {
     res = await fetchImpl(url, {
-      method: 'POST',
+      method,
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
     });
@@ -75,7 +68,7 @@ async function postMemoriesAction(flags, action, body, opts = {}) {
         .map((d) => `${Array.isArray(d.path) && d.path.length ? d.path.join('.') + ' ' : ''}${d.message || ''}`.trim())
         .join('; ');
     }
-    if (res.status === 400 && /unknown action|invalid action/i.test(msg)) {
+    if (action && res.status === 400 && /unknown action|invalid action/i.test(msg)) {
       msg += ` (is the server older than this CLI? '${action}' needs a matching Quilltap server)`;
     }
     throw new Error(msg);
@@ -83,4 +76,30 @@ async function postMemoriesAction(flags, action, body, opts = {}) {
   return payload;
 }
 
-module.exports = { postMemoriesAction, resolveMemoriesServerPort };
+/**
+ * POST `body` to `/api/v1/memories?action=<action>` and return the parsed
+ * payload. Throws an Error with a readable message on a connection failure
+ * or a non-2xx response.
+ *
+ * @param {object} flags            parsed memories flags (port / instance / dataDir)
+ * @param {string} action           the `?action=` name
+ * @param {object} body             JSON request body
+ * @param {object} [opts]
+ * @param {string} [opts.why]       one line on why the server is needed
+ * @param {(msg: string) => void} [opts.announce] called with the URL before the request
+ * @param {typeof fetch} [opts.fetchImpl] for tests
+ */
+async function postMemoriesAction(flags, action, body, opts = {}) {
+  return requestMemoriesApi(flags, 'POST', `/api/v1/memories?action=${encodeURIComponent(action)}`, body, { ...opts, action });
+}
+
+/**
+ * PUT a hand edit to `/api/v1/memories/<id>` (the edit chokepoint) and return
+ * the parsed payload (`{ memory }`). Same options and errors as
+ * {@link postMemoriesAction}.
+ */
+async function putMemory(flags, id, body, opts = {}) {
+  return requestMemoriesApi(flags, 'PUT', `/api/v1/memories/${encodeURIComponent(id)}`, body, opts);
+}
+
+module.exports = { postMemoriesAction, putMemory, resolveMemoriesServerPort };

package/lib/platform-paths.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Where an instance lives when nothing says otherwise.
+ *
+ * The CLI's mirror of the server's platform default (lib/paths.ts). Inside the
+ * Docker image the instance is always the bind mount at /app/quilltap, and the
+ * `nextjs` user has no home directory, so falling through to `~/.quilltap`
+ * sent `docker exec quilltap quilltap db …` to a database that does not exist
+ * and reported "no instance lock" while the server held one.
+ *
+ * Docker detection matches the server's lock-environment check
+ * (DOCKER_CONTAINER or /.dockerenv), deliberately without the server's
+ * "/app exists" heuristic, which misfires on hosts that happen to have /app.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DOCKER_BASE_DIR = '/app/quilltap';
+
+function isDockerContainer() {
+  if (process.env.DOCKER_CONTAINER === 'true') return true;
+  try {
+    return fs.existsSync('/.dockerenv');
+  } catch {
+    return false;
+  }
+}
+
+/** The instance root used when no flag, env var or registered instance names one. */
+function getDefaultBaseDir() {
+  if (isDockerContainer()) return DOCKER_BASE_DIR;
+  const home = os.homedir();
+  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Quilltap');
+  if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Quilltap');
+  return path.join(home, '.quilltap');
+}
+
+module.exports = {
+  DOCKER_BASE_DIR,
+  isDockerContainer,
+  getDefaultBaseDir,
+};

package/lib/recall-replay-command.js

@@ -61,7 +61,9 @@ Options:
                              multipliers
                              {RECALL_MULTIPLIERS key:
                              value}, specificAnchors, anchorMinHits,
-                             anchorOrder, backgroundReserve.
+                             anchorOrder, backgroundReserve,
+                             innerCircleShare, innerCircleAllowance
+                             ([3,2,1] = digests per member by tier).
                              Unknown keys are rejected.
       --tuning-file <path>   Read the --tuning JSON from a file
       --signals-from <path>  Reuse the signals saved in a previous --json

package/lib/theme-commands.js

@@ -21,6 +21,7 @@ const os = require('os');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 const { validateThemeBundle, validateManifest } = require('./theme-validation');
+const { getDefaultBaseDir } = require('./platform-paths');
 
 // ============================================================================
 // COLOR HELPERS
@@ -54,10 +55,7 @@ function resolveBaseDir(overrideDir) {
   if (process.env.QUILLTAP_DATA_DIR) {
     return process.env.QUILLTAP_DATA_DIR;
   }
-  const home = os.homedir();
-  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Quilltap');
-  if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Quilltap');
-  return path.join(home, '.quilltap');
+  return getDefaultBaseDir();
 }
 
 function getThemesDir(overrideDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.11.0-dev.11",
+  "version": "4.11.0-dev.110",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -36,7 +36,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@napi-rs/canvas": "^0.1.100",
+    "@napi-rs/canvas": "^1.0.13",
     "better-sqlite3-multiple-ciphers": "^12.11.1",
     "node-pty": "^1.1.0",
     "sharp": "^0.35.4",