@stackmemoryai/stackmemory 0.1.0

package/README.md

@@ -0,0 +1,317 @@
+# StackMemory
+
+**Lossless, project-scoped memory for AI tools**
+
+StackMemory is a **memory runtime** for AI coding and writing tools that preserves full project context across:
+
+* chat thread resets
+* model switching
+* editor restarts
+* long-running repos with thousands of interactions
+
+Instead of a linear chat log, StackMemory organizes memory as a **call stack** of scoped work (frames), allowing context to naturally unwind without lossy compaction.
+
+> **Memory is storage. Context is a compiled view.**
+
+---
+
+## Why StackMemory exists
+
+Modern AI tools forget:
+
+* why decisions were made
+* which constraints still apply
+* what changed earlier in the repo
+* what tools already ran and why
+
+StackMemory fixes this by:
+
+* storing **everything losslessly** (events, tool calls, decisions)
+* injecting only the **relevant working set** into model context
+* keeping memory **project-scoped**, not chat-scoped
+
+---
+
+## Core concepts (quick mental model)
+
+| Concept        | Meaning                                           |
+| -------------- | ------------------------------------------------- |
+| **Project**    | One GitHub repo (initial scope)                   |
+| **Frame**      | A scoped unit of work (like a function call)      |
+| **Call Stack** | Nested frames; only the active path is "hot"      |
+| **Event**      | Append-only record (message, tool call, decision) |
+| **Digest**     | Structured return value when a frame closes       |
+| **Anchor**     | Pinned fact (DECISION, CONSTRAINT, INTERFACE)     |
+
+Frames can span:
+
+* multiple chat turns
+* multiple tool calls
+* multiple sessions
+
+---
+
+## Hosted vs Open Source
+
+### Hosted (default)
+
+* Cloud-backed memory runtime
+* Fast indexing + retrieval
+* Durable storage
+* Per-project pricing
+* Works out-of-the-box
+
+### Open-source local mirror
+
+* SQLite-based
+* Fully inspectable
+* Offline / air-gapped
+* Intentionally **N versions behind**
+* No sync, no org features
+
+> OSS is for trust and inspection.
+> Hosted is for scale, performance, and teams.
+
+---
+
+## How it integrates
+
+StackMemory integrates as an **MCP tool** and is invoked on **every interaction** in:
+
+* Claude Code
+* compatible editors
+* future MCP-enabled tools
+
+The editor never manages memory directly — it simply asks StackMemory for the **context bundle**.
+
+---
+
+# QuickStart
+
+## 1. Hosted (Recommended)
+
+### Step 1: Create a project
+
+```bash
+stackmemory projects create \
+  --repo https://github.com/org/repo
+```
+
+This creates a **project-scoped memory space** tied to the repo.
+
+---
+
+### Step 2: Install MCP client
+
+```bash
+npm install -g stackmemory-mcp
+```
+
+or via binary:
+
+```bash
+curl -fsSL https://stackmemory.dev/install | sh
+```
+
+---
+
+### Step 3: Configure Claude Code / editor
+
+Add StackMemory as an MCP tool:
+
+```json
+{
+  "tools": {
+    "stackmemory": {
+      "command": "stackmemory-mcp",
+      "args": ["--project", "github:org/repo"]
+    }
+  }
+}
+```
+
+That's it.
+
+Every message now:
+
+1. Gets logged losslessly
+2. Updates the call stack
+3. Retrieves the correct context automatically
+
+No prompts to manage. No summaries to babysit.
+
+---
+
+## 2. Open-Source Local Mode
+
+### Step 1: Clone
+
+```bash
+git clone https://github.com/stackmemory/stackmemory
+cd stackmemory
+```
+
+### Step 2: Run local MCP server
+
+```bash
+cargo run --bin stackmemory-mcp
+# or
+npm run dev
+```
+
+This creates:
+
+```
+.memory/
+  └── memory.db   # SQLite
+```
+
+All project memory lives locally.
+
+---
+
+### Step 3: Point your editor to local MCP
+
+```json
+{
+  "tools": {
+    "stackmemory": {
+      "command": "stackmemory-mcp",
+      "args": ["--local"]
+    }
+  }
+}
+```
+
+---
+
+## What happens on each interaction
+
+On every message/tool call:
+
+1. **Ingest**
+
+   * New message delta is appended as events
+
+2. **Index**
+
+   * Anchors updated
+   * Digests generated when frames close
+
+3. **Retrieve**
+
+   * Active call stack (hot)
+   * Relevant digests (warm)
+   * Pointers to raw data (cold)
+
+4. **Return context bundle**
+
+   * Sized to token budget
+   * No global compaction
+
+---
+
+## Example MCP response (simplified)
+
+```json
+{
+  "hot_stack": [
+    { "frame": "Debug auth redirect", "constraints": [...] }
+  ],
+  "anchors": [
+    { "type": "DECISION", "text": "Use SameSite=Lax cookies" }
+  ],
+  "relevant_digests": [
+    { "frame": "Initial auth refactor", "summary": "..." }
+  ],
+  "pointers": [
+    "s3://logs/auth-test-0421"
+  ]
+}
+```
+
+---
+
+## Storage & limits
+
+### Free tier (hosted)
+
+* 1 project
+* Up to **X MB stored**
+* Up to **Y MB retrieval egress / month**
+
+### Paid tiers
+
+* Per-project pricing
+* Higher storage + retrieval
+* Team sharing
+* Org controls
+
+**No seat-based pricing.**
+
+---
+
+## Guarantees
+
+* ✅ Lossless storage (no destructive compaction)
+* ✅ Project-scoped isolation
+* ✅ Survives new chat threads
+* ✅ Survives model switching
+* ✅ Inspectable local mirror
+
+---
+
+## Non-goals
+
+* ❌ Chat UI
+* ❌ Vector DB replacement
+* ❌ Tool execution runtime
+* ❌ Prompt engineering framework
+
+---
+
+## Philosophy
+
+> **Frames instead of transcripts.
+> Return values instead of summaries.
+> Storage separate from context.**
+
+---
+
+## Status
+
+* Hosted: **Private beta**
+* OSS mirror: **Early preview**
+* MCP integration: **Stable**
+
+---
+
+## Roadmap (high level)
+
+* Team / org projects
+* Cross-repo memory
+* Background project compilers
+* Fine-grained retention policies
+* Editor UX surfacing frame boundaries
+
+---
+
+## License
+
+* Hosted service: Proprietary
+* Open-source mirror: Apache 2.0 / MIT (TBD)
+
+---
+
+## Additional Resources
+
+### ML System Design
+- [ML System Insights](./ML_SYSTEM_INSIGHTS.md) - Comprehensive analysis of 300+ production ML systems
+- [Agent Instructions](./AGENTS.md) - Specific guidance for AI agents working with ML systems
+
+### Documentation
+- [Product Requirements](./PRD.md) - Detailed product specifications
+- [Technical Architecture](./TECHNICAL_ARCHITECTURE.md) - System design and database schemas
+- [Beads Integration](./BEADS_INTEGRATION.md) - Git-native memory patterns from Beads ecosystem
+
+---

package/dist/attention-scoring/src/attention-tracker.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Attention-Based Importance Scoring System
+ *
+ * Tracks which context pieces actually influence AI decisions
+ * and adjusts their importance scores based on real usage
+ */
+import { EventEmitter } from 'events';
+export declare class AttentionTracker extends EventEmitter {
+    private db;
+    private currentSession;
+    private attentionBuffer;
+    constructor(dbPath?: string);
+    private initDB;
+    private createSession;
+    startProvision(query: string): ProvisionBuilder;
+    trackProvision(contextItems: ContextItem[], provisionId: string): void;
+    trackResponse(provisionId: string, query: string, response: string, actionsTaken?: string[]): string;
+    private analyzeAttention;
+    private calculateInfluence;
+    private updateLearnedImportance;
+    private detectPatterns;
+    reinforcementUpdate(feedback: UserFeedback): Promise<void>;
+    getImportanceScore(contextId: string): number;
+    getContextRanking(contextType?: string): ContextRanking[];
+    getRecommendedContext(query: string, currentContext: string[]): string[];
+    getAttentionHeatmap(sessionId?: string): AttentionHeatmap;
+    private generateId;
+    private hashContent;
+    private estimateTokens;
+    private extractKeywords;
+    private countMentions;
+    private getContextContent;
+    private correlateWithActions;
+    private calculateSimilarity;
+    private evaluateSuccess;
+}
+export declare class ProvisionBuilder {
+    private tracker;
+    private provisionId;
+    private query;
+    private contexts;
+    constructor(tracker: AttentionTracker, provisionId: string, query: string);
+    add(context: ContextItem): this;
+    addMany(contexts: ContextItem[]): this;
+    execute(handler: (contexts: ContextItem[]) => Promise<string>): Promise<TrackedResponse>;
+}
+export interface ContextItem {
+    id: string;
+    type: string;
+    content: string;
+    tokenCount: number;
+    importance?: number;
+}
+export interface UserFeedback {
+    responseId: string;
+    helpful: boolean;
+    specific?: string;
+}
+export interface ContextRanking {
+    contextId: string;
+    type: string;
+    importance: number;
+    influenceRate: number;
+    avgInfluence: number;
+    lastUsed: number;
+}
+export interface AttentionHeatmap {
+    positions: number[];
+    influences: number[];
+    contextIds: string[];
+}
+interface TrackedResponse {
+    responseId: string;
+    response: string;
+    latency: number;
+    contextsUsed: number;
+}
+export default AttentionTracker;
+//# sourceMappingURL=attention-tracker.d.ts.map

package/dist/attention-scoring/src/attention-tracker.d.ts.map

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