{"_id":"@577-industries/agent-memory","name":"@577-industries/agent-memory","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@577-industries/agent-memory","version":"1.0.0","description":"Bio-inspired memory for AI agents with logarithmic reinforcement, exponential decay, and composite recall scoring","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit"},"keywords":["memory","ai-agent","reinforcement","decay","recall","bio-inspired","embeddings","semantic"],"author":{"name":"577 Industries"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/577-industries/agent-memory.git"},"homepage":"https://www.577industries.com/forge","devDependencies":{"@types/node":"^25.4.0","tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@577-industries/agent-memory@1.0.0","gitHead":"565750815f7ea774ddbae928ef9fb9492d91343a","bugs":{"url":"https://github.com/577-industries/agent-memory/issues"},"_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-SixAb0V3ORwMgCThiP3Y9Gut1Fu37nvrTgm+7zCQHM69KNcZ8HsXpLoJ7OjkxDJu/0WwCxk1WowrY2RUvbipjw==","shasum":"e2cba694afe523026d5633e51fe54bce5007cf67","tarball":"https://registry.npmjs.org/@577-industries/agent-memory/-/agent-memory-1.0.0.tgz","fileCount":7,"unpackedSize":36987,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHFRz8cRBdhkboe5PjElv/LQhH1IOziMXCQ/CdUjQ42aAiB/Ih4QvGqQEQZ9+QToxSfCOJ6VPrmPJ/b8u1Hu8AYK8g=="}]},"_npmUser":{"name":"577industries","email":"t.waweru@577industries.com"},"directories":{},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-memory_1.0.0_1773252953684_0.04096898594344256"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T18:15:53.536Z","1.0.0":"2026-03-11T18:15:53.854Z","modified":"2026-03-11T18:15:54.139Z"},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"description":"Bio-inspired memory for AI agents with logarithmic reinforcement, exponential decay, and composite recall scoring","homepage":"https://www.577industries.com/forge","keywords":["memory","ai-agent","reinforcement","decay","recall","bio-inspired","embeddings","semantic"],"repository":{"type":"git","url":"git+https://github.com/577-industries/agent-memory.git"},"author":{"name":"577 Industries"},"bugs":{"url":"https://github.com/577-industries/agent-memory/issues"},"license":"Apache-2.0","readme":"# @577-industries/agent-memory\r\n\r\n[![npm version](https://img.shields.io/npm/v/@577-industries/agent-memory)](https://www.npmjs.com/package/@577-industries/agent-memory)\r\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\r\n\r\nBio-inspired memory for AI agents with 5 memory types, logarithmic reinforcement, exponential decay, and composite recall scoring. Mimics biological memory consolidation. Zero runtime dependencies.\r\n\r\nImplements the core algorithm described in the **\"Autonomous Memory Evolution\"** patent (December 2025) by 577 Industries.\r\n\r\n## How It Works\r\n\r\n```\r\n  Input ──► Store ──► [Duplicate?] ──yes──► Reinforce\r\n                          │                    │\r\n                          no             confidence +=\r\n                          │              0.1/ln(count+2)\r\n                          ▼\r\n                    New Memory (0.5)\r\n\r\n  Recall ──► Score = similarity × 0.7 + confidence × 0.3 ──► Ranked Results\r\n\r\n  Decay  ──► confidence *= 0.95 (per 30d unreinforced) ──► delete if < 0.1\r\n```\r\n\r\n## Quick Start\r\n\r\n```bash\r\nnpm install @577-industries/agent-memory\r\n```\r\n\r\n```typescript\r\nimport { MemoryStore } from \"@577-industries/agent-memory\";\r\n\r\nconst store = new MemoryStore({ agentId: \"my-agent\" });\r\n\r\n// Store memories (auto-deduplicates)\r\nawait store.store(\"pattern\", \"Users ask about pricing first\");\r\nawait store.store(\"preference\", \"Prefers bullet-point summaries\");\r\n\r\n// Reinforce when pattern repeats\r\nawait store.store(\"pattern\", \"Users ask about pricing first\");\r\n// → { reinforced: true } — confidence increases logarithmically\r\n\r\n// Recall top memories\r\nconst memories = await store.recall(undefined, 5);\r\n\r\n// Format for LLM system prompt\r\nconst prompt = store.format(memories);\r\n// → \"## Agent Memory\\n- [pattern] Users ask about...\"\r\n\r\n// Simulate time passing and decay\r\nstore.advanceTime(35); // 35 days\r\nstore.decay(); // → { decayed: N, deleted: M }\r\n```\r\n\r\n## Memory Types\r\n\r\n| Type | Purpose |\r\n|------|---------|\r\n| `pattern` | Recurring workflow or behavior |\r\n| `preference` | User preference or style |\r\n| `baseline` | Metric or normal value |\r\n| `entity` | Key entity or relationship |\r\n| `insight` | Strategic observation |\r\n\r\n## API Reference\r\n\r\n### `MemoryStore`\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `new MemoryStore(config)` | Create a store with optional embedding provider |\r\n| `store(type, content)` | Store or reinforce a memory |\r\n| `recall(query?, limit?)` | Recall ranked memories |\r\n| `reinforce(id)` | Manually reinforce a memory |\r\n| `decay()` | Run a decay cycle |\r\n| `format(memories?)` | Format for LLM prompt injection |\r\n| `getAll()` | Get all stored memories |\r\n| `advanceTime(days)` | Simulate time passing |\r\n\r\n### Pluggable Embeddings\r\n\r\n```typescript\r\ninterface EmbeddingProvider {\r\n  embed(text: string): Promise<number[]>;\r\n}\r\n```\r\n\r\nWithout an embedding provider, the store falls back to substring matching for deduplication and confidence-only ranking for recall.\r\n\r\n### Standalone Functions\r\n\r\n| Function | Description |\r\n|----------|-------------|\r\n| `computeReinforcement(confidence, count)` | Logarithmic reinforcement formula |\r\n| `applyDecay(memories, config)` | Exponential decay with cleanup |\r\n| `scoreMemories(memories, embedding?, options?)` | Composite recall scoring |\r\n| `cosineSimilarity(a, b)` | Vector cosine similarity |\r\n| `formatMemoriesForPrompt(memories)` | Format for LLM injection |\r\n\r\n## Architecture\r\n\r\nThree bio-inspired mechanisms:\r\n\r\n1. **Reinforcement** — `confidence += 0.1 / ln(count + 2)` — logarithmic growth with diminishing returns\r\n2. **Decay** — `confidence *= 0.95` per 30-day unreinforced cycle — exponential fade\r\n3. **Recall** — `score = similarity × 0.7 + confidence × 0.3` — composite ranking\r\n\r\nBased on the [\"Autonomous Memory Evolution\" patent](https://www.577industries.com/forge) by 577 Industries.\r\n\r\n---\r\n\r\nExtracted from [FORGE OS](https://www.577industries.com) by **577 Industries**.\r\n","readmeFilename":"README.md","_rev":"1-5552d16e0f5f00da56e11a097f4dace9"}