pi-memory-strata 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 memory-strata contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Memory Strata — 四层分层记忆架构
+
+> Four-layer stratified memory architecture for long-horizon AI agent projects.
+> Solves critical fact forgetting, memory bloat, and knowledge sedimentation failures.
+
+---
+
+## Architecture
+
+```
+L1  System Injection   MEMORY.md — key points + anchors        (auto-loaded every session)
+L2  Project Core       project-core.md — stable facts + ADR     (rarely changes)
+L3  Dev Status         dev-status.md — progress/params/issues     (updates with progress)
+L4  Daily Journal      YYYY-MM-DD.md — session log              (per-session)
+```
+
+## Three Mechanisms
+
+### 1. Auto-Distillation (Episodic → Semantic)
+
+- L4→L3: milestone completed, or referenced across ≥2 sessions
+- L3→L2: stable ≥1 month + confirmed fact + likely needed in future
+- L2→L1: useful beyond this project (user preferences, general lessons)
+
+### 2. Memory Strength Decay (`last_used`)
+
+- Tag entries with `[last_used: YYYY-MM-DD]`
+- >14 days unused → ⚡ rarely used
+- >30 days unused → auto-archive
+
+### 3. Zettelkasten Link Enhancement
+
+- Bidirectional `[[...]]` links between L2↔L3
+- Check link integrity with the distillation script
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+npx pi-memory-strata init-project <project-name>
+```
+
+### 2. Run daily maintenance (or schedule with cron)
+
+```bash
+npx pi-memory-strata maintain --vault /path/to/vault
+```
+
+### 3. Check memory health
+
+```bash
+npx pi-memory-strata check --vault /path/to/vault
+```
+
+## Installation
+
+### As Pi Extension
+
+```bash
+pi install npm:pi-memory-strata
+```
+
+### As npm package
+
+```bash
+npm install -g pi-memory-strata
+```
+
+### Direct usage (no install)
+
+```bash
+npx pi-memory-strata <command>
+```
+
+## Programmatic API
+
+```typescript
+import { MemoryStrata } from 'pi-memory-strata';
+
+const strata = new MemoryStrata({
+  vaultPath: '/path/to/obsidian-vault',
+  autoArchiveDays: 30,
+  staleWarningDays: 14,
+});
+
+// Run distillation check
+const check = await strata.check();
+console.log(check.ok);
+
+// Run daily maintenance
+const report = await strata.maintain();
+console.log(report.health);
+
+// Initialize new project
+strata.initProject('my-project');
+```
+
+## Vault Structure
+
+```
+obsidian-vault/
+├── 00-brain/
+│   └── MEMORY.md              # L1: System injection
+├── 10-journal/
+│   ├── maintenance/           # Daily maintenance reports
+│   ├── summary/               # Auto-generated daily summaries
+│   └── 2026-01-01.md        # L4: Daily logs
+├── 20-projects/
+│   └── my-project/
+│       ├── dev-status.md    # L3: Development status
+│       └── project-core.md  # L2: Project core archive
+├── 30-knowledge/
+├── 60-learnings/
+│   └── archive/             # Auto-archived entries
+├── scripts/
+│   ├── memory_distill_check.py
+│   └── daily_memory_maintenance.py
+└── templates/
+    ├── 01-status.md
+    └── 02-core.md
+```
+
+## Daily Maintenance (Automated)
+
+Schedule daily maintenance with cron or systemd:
+
+```bash
+# Every day at 09:30
+30 9 * * * npx pi-memory-strata maintain
+```
+
+Maintenance performs:
+1. **Journal coverage check** — verify last 7 days have logs
+2. **Dev status freshness** — warn if >7 days without update
+3. **Core archive freshness** — warn if >30 days without update
+4. **Memory decay** — identify entries with stale `last_used`
+5. **Anchor integrity** — verify memory anchors exist
+6. **Bidirectional links** — check L2↔L3 link completeness
+7. **Auto-archive** — move >30d stale entries to `60-learnings/archive/`
+8. **Daily summary** — generate previous day's summary
+
+## Academic Context
+
+| Concept | Source | This Package |
+|---------|--------|-------------|
+| Write-Manage-Read loop | arXiv:2603.07670 | W(journal) + M(distill/decay) + R(search) |
+| Episodic→Semantic promotion | A-MEM (NeurIPS 2025) | L4→L3→L2 distillation |
+| Memory strength decay | MemoryBank (2024) | `last_used` + 30-day archive |
+| Zettelkasten linking | A-MEM | Obsidian `[[...]]` bidirectional links |
+| Atomic facts | AtomMem (2026) | Memory anchors with consequence tags |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { MemoryStrata } from './index.js';
+const program = new Command();
+program
+    .name('pi-memory-strata')
+    .description('Four-layer stratified memory architecture for long-horizon AI agent projects')
+    .version('0.1.0');
+program
+    .command('check')
+    .description('Run distillation check on memory system')
+    .option('-v, --vault <path>', 'Path to Obsidian vault')
+    .action(async (options) => {
+    const strata = new MemoryStrata({ vaultPath: options.vault });
+    try {
+        const result = await strata.check();
+        console.log('Distillation check completed:', result.ok ? 'OK' : 'WARN');
+        if (!result.ok) {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error('Check failed:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('maintain')
+    .description('Run daily maintenance routine')
+    .option('-v, --vault <path>', 'Path to Obsidian vault')
+    .option('--dry-run', 'Only check, do not modify')
+    .action(async (options) => {
+    const strata = new MemoryStrata({ vaultPath: options.vault });
+    try {
+        const report = await strata.maintain();
+        console.log('Maintenance completed:', report.date);
+        console.log('Health:', JSON.stringify(report.health, null, 2));
+        console.log('Issues:', report.issues.length);
+        console.log('Suggestions:', report.suggestions.length);
+    }
+    catch (err) {
+        console.error('Maintenance failed:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('init-project')
+    .description('Initialize a new project in the vault')
+    .argument('<name>', 'Project name')
+    .option('-v, --vault <path>', 'Path to Obsidian vault')
+    .action((name, options) => {
+    const strata = new MemoryStrata({ vaultPath: options.vault });
+    try {
+        strata.initProject(name);
+        console.log(`Project initialized: ${name}`);
+    }
+    catch (err) {
+        console.error('Init failed:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { MemoryConfig, MaintenanceReport, DistillCheckResult } from './types.js';
+export declare class MemoryStrata {
+    private config;
+    private vaultPath;
+    constructor(config?: Partial<MemoryConfig>);
+    /**
+     * Run the Python distillation check script
+     */
+    check(): Promise<DistillCheckResult>;
+    /**
+     * Run the daily maintenance routine
+     */
+    maintain(): Promise<MaintenanceReport>;
+    /**
+     * Initialize a new project in the vault
+     */
+    initProject(projectName: string): void;
+    private parseCheckOutput;
+    private parseMaintenanceOutput;
+}
+export { MemoryConfig, MaintenanceReport, DistillCheckResult, ProjectInfo } from './types.js';

package/dist/index.js

@@ -0,0 +1,80 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+export class MemoryStrata {
+    config;
+    vaultPath;
+    constructor(config) {
+        this.config = {
+            vaultPath: process.env.OBSIDIAN_VAULT_PATH || '',
+            autoArchiveDays: 30,
+            staleWarningDays: 14,
+            journalCheckDays: 7,
+            ...config,
+        };
+        this.vaultPath = this.config.vaultPath;
+    }
+    /**
+     * Run the Python distillation check script
+     */
+    async check() {
+        const scriptPath = resolve(import.meta.dirname, '../scripts/memory_distill_check.py');
+        if (!existsSync(scriptPath)) {
+            throw new Error(`Script not found: ${scriptPath}`);
+        }
+        const result = execSync(`python "${scriptPath}" --vault "${this.vaultPath}"`, { encoding: 'utf-8', cwd: this.vaultPath });
+        return this.parseCheckOutput(result);
+    }
+    /**
+     * Run the daily maintenance routine
+     */
+    async maintain() {
+        const scriptPath = resolve(import.meta.dirname, '../scripts/daily_memory_maintenance.py');
+        if (!existsSync(scriptPath)) {
+            throw new Error(`Maintenance script not found: ${scriptPath}`);
+        }
+        const result = execSync(`python "${scriptPath}" --vault "${this.vaultPath}"`, { encoding: 'utf-8', cwd: this.vaultPath });
+        return this.parseMaintenanceOutput(result);
+    }
+    /**
+     * Initialize a new project in the vault
+     */
+    initProject(projectName) {
+        const projectDir = resolve(this.vaultPath, '20-projects', projectName);
+        if (existsSync(projectDir)) {
+            throw new Error(`Project already exists: ${projectName}`);
+        }
+        // Copy templates
+        const templatesDir = resolve(import.meta.dirname, '../templates');
+        execSync(`mkdir -p "${projectDir}" && cp "${templatesDir}/01-status.md" "${projectDir}/dev-status.md" && cp "${templatesDir}/02-core.md" "${projectDir}/project-core.md"`, { encoding: 'utf-8' });
+    }
+    parseCheckOutput(output) {
+        // Parse the output of memory_distill_check.py
+        // This is a simplified parser - the actual implementation would parse the full output
+        return {
+            ok: !output.includes('MISSING') && !output.includes('STALE'),
+            projects: [],
+            journalMissingDays: [],
+            staleEntries: [],
+            missingAnchors: [],
+        };
+    }
+    parseMaintenanceOutput(output) {
+        // Parse the output of daily_memory_maintenance.py
+        const health = {
+            journalCoverage: output.includes('L4 journal') && output.includes('MISSING') ? 'warn' : 'ok',
+            devStatus: output.includes('dev status') && output.includes('STALE') ? 'warn' : 'ok',
+            coreArchive: output.includes('core archive') && output.includes('STALE') ? 'warn' : 'ok',
+            memoryDecay: output.includes('archiving') ? 'warn' : 'ok',
+            anchorIntegrity: output.includes('No anchor') ? 'warn' : 'ok',
+            bidirectionalLinks: output.includes('incomplete') ? 'warn' : 'ok',
+        };
+        return {
+            date: new Date().toISOString().split('T')[0],
+            health,
+            issues: [],
+            suggestions: [],
+            archivedCount: 0,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Types for Pi Memory Strata extension
+ */
+export interface MemoryVault {
+    root: string;
+    brain: string;
+    journal: string;
+    projects: string;
+    knowledge: string;
+    learnings: string;
+    templates: string;
+    scripts: string;
+}
+export interface MaintenanceReport {
+    date: string;
+    health: {
+        journalCoverage: 'ok' | 'warn';
+        devStatus: 'ok' | 'warn';
+        coreArchive: 'ok' | 'warn';
+        memoryDecay: 'ok' | 'warn';
+        anchorIntegrity: 'ok' | 'warn';
+        bidirectionalLinks: 'ok' | 'warn';
+    };
+    issues: string[];
+    suggestions: string[];
+    archivedCount: number;
+    summaryPath?: string;
+}
+export interface ProjectInfo {
+    name: string;
+    statusPath: string;
+    corePath: string;
+    lastStatusUpdate?: string;
+    lastCoreUpdate?: string;
+    daysSinceStatusUpdate?: number;
+    daysSinceCoreUpdate?: number;
+    bidirectionalLinks: boolean;
+}
+export interface DistillCheckResult {
+    ok: boolean;
+    projects: ProjectInfo[];
+    journalMissingDays: string[];
+    staleEntries: string[];
+    missingAnchors: string[];
+}
+export interface MemoryConfig {
+    vaultPath: string;
+    autoArchiveDays: number;
+    staleWarningDays: number;
+    journalCheckDays: number;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for Pi Memory Strata extension
+ */
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pi-memory-strata",
+  "version": "0.1.0",
+  "description": "Four-layer stratified memory architecture for long-horizon AI agent projects. Auto-distillation, memory decay, and Obsidian vault integration.",
+  "type": "module",
+  "piConfig": {
+    "configDir": ".pi"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pi-memory-strata": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "memory",
+    "stratified-memory",
+    "obsidian",
+    "long-horizon",
+    "agent-memory"
+  ],
+  "author": "bailianfa",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}