@kentwynn/kgraph 0.2.33 → 0.2.35

package/README.md

@@ -253,9 +253,10 @@ kgraph repair
 kgraph uninstall
 kgraph uninstall --yes
 kgraph uninstall --keep-integrations --yes
+kgraph uninstall --yes --memory
 ```
 
-`uninstall` previews repo-local removal and does not delete anything unless `--yes` is passed. `uninstall --yes` removes `.kgraph/` and KGraph-managed integration blocks/files while preserving source files and user-authored text outside managed blocks. Use `--keep-integrations --yes` to remove only `.kgraph/` while leaving AI tool instruction files in place. After uninstalling, `kgraph init` can be run again for a fresh setup.
+`uninstall` previews repo-local removal and does not delete anything unless `--yes` is passed. `uninstall --yes` removes `.kgraph/` and KGraph-managed integration blocks/files while preserving source files and user-authored text outside managed blocks. Use `--keep-integrations --yes` to remove only `.kgraph/` while leaving AI tool instruction files in place. Add `--memory` to also remove the Copilot memory rule that `init` installs; without this flag the memory entry is preserved across uninstalls. After uninstalling, `kgraph init` can be run again for a fresh setup.
 
 ```bash
 kgraph impact "Button"

package/dist/cli/commands/init.js

@@ -1,4 +1,5 @@
 import { loadConfig, saveConfig, writeDefaultConfig, } from '../../config/config.js';
+import { installCopilotMemory } from '../../integrations/copilot-memory.js';
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations } from '../../integrations/integration-store.js';
 import { ensureKnowledgeStore } from '../../knowledge/atom-store.js';
@@ -85,6 +86,11 @@ export function registerInitCommand(program) {
                 });
             }
         }
+        // Install Copilot memory entry
+        const installed = await installCopilotMemory();
+        if (installed) {
+            console.log('Copilot memory rule installed.');
+        }
         console.log('');
         console.log(renderInitSummary({
             files: result.files,

package/dist/cli/commands/uninstall.js

@@ -1,6 +1,7 @@
 import { readdir, rm, rmdir } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig } from '../../config/config.js';
+import { removeCopilotMemory } from '../../integrations/copilot-memory.js';
 import { removeIntegrations } from '../../integrations/integration-store.js';
 import { pathExists, resolveWorkspace } from '../../storage/kgraph-paths.js';
 import { runCommand } from '../errors.js';
@@ -15,6 +16,7 @@ export function registerUninstallCommand(program) {
         .description('Remove KGraph from this repository')
         .option('--yes', 'Apply the uninstall after previewing what will be removed')
         .option('--keep-integrations', 'Remove only .kgraph/ and preserve generated AI tool instruction files')
+        .option('--memory', 'Also remove the global Copilot memory entry for this repo')
         .action((options) => runCommand(async () => {
         const workspace = resolveWorkspace(process.cwd());
         const initialized = await pathExists(workspace.kgraphPath);
@@ -25,6 +27,7 @@ export function registerUninstallCommand(program) {
             initialized,
             integrations: configuredIntegrations,
             keepIntegrations: options.keepIntegrations === true,
+            removeMemory: options.memory === true,
             applying: options.yes === true,
         });
         if (!options.yes) {
@@ -39,6 +42,13 @@ export function registerUninstallCommand(program) {
         if (initialized) {
             await rm(workspace.kgraphPath, { recursive: true, force: true });
         }
+        // Remove Copilot memory entry only if --memory flag is set
+        if (options.memory) {
+            const memoryRemoved = await removeCopilotMemory();
+            if (memoryRemoved) {
+                console.log('Removed Copilot memory rule.');
+            }
+        }
         console.log('');
         console.log('KGraph uninstall complete.');
         console.log('Run `kgraph init` to set up this repository again.');
@@ -84,6 +94,9 @@ function printUninstallPreview(input) {
             console.log('- No configured integration blocks/files found');
         }
     }
+    if (input.removeMemory) {
+        console.log('- Copilot memory rule for this repo');
+    }
     console.log('');
     console.log('Will preserve:');
     console.log('- Repository source files');

package/dist/cli/help.js

@@ -11,7 +11,10 @@ export function renderRootHelp(useColor = supportsColor()) {
             ['purpose', 'durable engineering memory for AI coding tools'],
             ['storage', '.kgraph/ atoms, maps, indexes, and session history'],
             ['stance', 'local-first · deterministic-first · inspectable'],
-            ['agents', 'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline'],
+            [
+                'agents',
+                'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline',
+            ],
         ]),
         '',
         sectionTitle(theme, `${accent} Usage`),
@@ -49,6 +52,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('repair', 'Clean noisy stale atom references'),
         command('uninstall', 'Preview repo-local KGraph removal'),
         command('uninstall --yes', 'Remove .kgraph/ and managed integrations'),
+        command('uninstall --yes --memory', 'Also remove Copilot memory rule'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
         '',

package/dist/integrations/copilot-memory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve the Copilot memory-tool memories directory for the current OS.
+ * Returns undefined if the globalStorage root cannot be determined.
+ * Respects KGRAPH_COPILOT_MEMORY_DIR env override for testing.
+ */
+export declare function resolveCopilotMemoryDir(): string | undefined;
+/**
+ * Install the KGraph memory entry into the Copilot memory store.
+ * Returns true if written, false if the directory could not be resolved.
+ */
+export declare function installCopilotMemory(): Promise<boolean>;
+/**
+ * Remove the KGraph memory entry from the Copilot memory store.
+ * Returns true if removed or did not exist, false if the directory could not be resolved.
+ */
+export declare function removeCopilotMemory(): Promise<boolean>;
+/**
+ * Check whether the KGraph memory entry exists.
+ */
+export declare function hasCopilotMemory(): Promise<boolean>;
+/**
+ * Read the KGraph memory content, if it exists.
+ */
+export declare function readCopilotMemory(): Promise<string | undefined>;

package/dist/integrations/copilot-memory.js

@@ -0,0 +1,87 @@
+/**
+ * Manages the GitHub Copilot memory-tool entry for KGraph.
+ * Installs/removes a persistent preference so Copilot always follows the
+ * KGraph workflow in repos where KGraph is initialised.
+ */
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import path from 'node:path';
+import { pathExists } from '../storage/kgraph-paths.js';
+const MEMORY_FILE = 'kgraph.md';
+const MEMORY_CONTENT = `# KGraph
+
+- KGraph is installed. Follow the copilot-instructions.md and @kgraph agent for this repo.
+`;
+/**
+ * Resolve the Copilot memory-tool memories directory for the current OS.
+ * Returns undefined if the globalStorage root cannot be determined.
+ * Respects KGRAPH_COPILOT_MEMORY_DIR env override for testing.
+ */
+export function resolveCopilotMemoryDir() {
+    if (process.env['KGRAPH_COPILOT_MEMORY_DIR']) {
+        return process.env['KGRAPH_COPILOT_MEMORY_DIR'];
+    }
+    const home = homedir();
+    switch (platform()) {
+        case 'win32':
+            return path.join(process.env['APPDATA'] ?? path.join(home, 'AppData', 'Roaming'), 'Code', 'User', 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories');
+        case 'darwin':
+            return path.join(home, 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories');
+        case 'linux':
+            return path.join(process.env['XDG_CONFIG_HOME'] ?? path.join(home, '.config'), 'Code', 'User', 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories');
+        default:
+            return undefined;
+    }
+}
+/**
+ * Install the KGraph memory entry into the Copilot memory store.
+ * Returns true if written, false if the directory could not be resolved.
+ */
+export async function installCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return false;
+    }
+    await mkdir(memoryDir, { recursive: true });
+    await writeFile(path.join(memoryDir, MEMORY_FILE), MEMORY_CONTENT, 'utf8');
+    return true;
+}
+/**
+ * Remove the KGraph memory entry from the Copilot memory store.
+ * Returns true if removed or did not exist, false if the directory could not be resolved.
+ */
+export async function removeCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return false;
+    }
+    const memoryFile = path.join(memoryDir, MEMORY_FILE);
+    if (await pathExists(memoryFile)) {
+        await rm(memoryFile, { force: true });
+    }
+    return true;
+}
+/**
+ * Check whether the KGraph memory entry exists.
+ */
+export async function hasCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return false;
+    }
+    return pathExists(path.join(memoryDir, MEMORY_FILE));
+}
+/**
+ * Read the KGraph memory content, if it exists.
+ */
+export async function readCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return undefined;
+    }
+    const memoryFile = path.join(memoryDir, MEMORY_FILE);
+    if (!(await pathExists(memoryFile))) {
+        return undefined;
+    }
+    return readFile(memoryFile, 'utf8');
+}

package/dist/integrations/workflow-steps.js

@@ -2,6 +2,25 @@
  * Shared KGraph workflow step strings used across all AI tool adapters.
  * Update here once instead of in each adapter file.
  */
+const DECISION_CONTEXT = `## Feature intent — choose based on the situation
+
+**Sessions** exist to preserve the journey when exploration, evaluation, or multi-step reasoning produced knowledge that the outcome alone cannot capture. The path matters when a future agent might face the same fork.
+
+**Inbox notes** exist for structured multi-section knowledge that cannot fit a single --capture sentence. Architecture decisions with rationale, multi-file change summaries with interconnections, or design tradeoffs with rejected alternatives.
+
+**--capture / conclude** exists for atomic durable conclusions — one sentence, evidence-linked. Prefer this for most captures.
+
+**--domain and --tag** exist so future queries find knowledge by area, not just by word match. Add them when the knowledge clearly belongs to an identifiable architectural boundary.
+
+**knowledge supersede** exists to evolve knowledge without duplicating. When new understanding contradicts or refines an existing atom, supersede it.
+
+**stale** exists to surface atoms whose evidence no longer holds. Consider it after your edits touched code that pack showed as atom-referenced.
+
+**impact** exists to reveal blast radius. Consider it before destructive changes to public interfaces — renames, deletions, signature changes.
+
+**compact** exists to merge redundant knowledge. Consider it when you store something that feels overlapping with what pack already showed.
+
+**scan** exists to refresh maps after structural changes. The root workflow handles this automatically unless you created, deleted, or renamed many files outside of kgraph commands.`;
 const DOCTOR_STEP = `Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.`;
 const IMPACT_STEP = `Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.`;
 const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/noisy atom refs need fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.`;
@@ -42,7 +61,9 @@ export function numberedWorkflow(agentName, options = {}) {
 13. ${REPAIR_STEP}
 14. ${COMPACT_STEP}
 15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph locally with PNG export.
-16. ${HISTORY_STEP}`;
+16. ${HISTORY_STEP}
+
+${DECISION_CONTEXT}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -64,5 +85,7 @@ export function bulletWorkflow(agentName, options = {}) {
 - ${REPAIR_STEP}
 - ${COMPACT_STEP}
 - Run \`kgraph visualize\` to open the interactive dependency graph locally with PNG export.
-- ${HISTORY_STEP}`;
+- ${HISTORY_STEP}
+
+${DECISION_CONTEXT}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {