{"_id":"@agents-eco/agentic-memory","_rev":"2-d0e5573520095ae0a36f640e7b60fdd5","name":"@agents-eco/agentic-memory","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agents-eco/agentic-memory","version":"0.1.0","keywords":["agents","ai","memory","graph","stm","ltm","short-term-memory","long-term-memory","voyage","embeddings","agents-eco","agentic"],"author":{"name":"agents.eco"},"license":"MIT","_id":"@agents-eco/agentic-memory@0.1.0","maintainers":[{"name":"dudenpc","email":"ramankrishna10@gmail.com"}],"homepage":"https://agents.eco","bugs":{"url":"https://github.com/agents-eco/agentic-memory/issues"},"dist":{"shasum":"783ebf3923f0d4e572fed707185eb25dab676cac","tarball":"https://registry.npmjs.org/@agents-eco/agentic-memory/-/agentic-memory-0.1.0.tgz","fileCount":39,"integrity":"sha512-+C4W9rGkiQuN6SztUzJBXWdpuUuBFEMs/zZNPBV23eYr1OkjK6WuhX5HfYEMYLe3X9dkGpvRJLJHSX1Vqo/7cw==","signatures":[{"sig":"MEUCIQCa8tbpPgkp5TmhiQHC9L3yBTRYhcS8SlKjG7lYCV4A1AIgL0NwTZaXPjH9w46+5fwgGB7VlPkufU4ar5Xg1IvqYmw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":127925},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d361da0318d2a4699a3e4874f00be4c377da0046","scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist"},"_npmUser":{"name":"dudenpc","email":"ramankrishna10@gmail.com"},"repository":{"url":"git+https://github.com/agents-eco/agentic-memory.git","type":"git"},"_npmVersion":"11.6.2","description":"Graph-based agent memory — short-term and long-term memory with local or Voyage AI backends. Built for agents.eco.","directories":{},"_nodeVersion":"25.2.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/agentic-memory_0.1.0_1771461191644_0.009698161677497597","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Moved to @bottensor/agentic-memory. Run: npm install @bottensor/agentic-memory"}},"time":{"created":"2026-02-19T00:33:11.573Z","modified":"2026-03-28T01:36:54.957Z","0.1.0":"2026-02-19T00:33:11.834Z"},"bugs":{"url":"https://github.com/agents-eco/agentic-memory/issues"},"author":{"name":"agents.eco"},"license":"MIT","homepage":"https://agents.eco","keywords":["agents","ai","memory","graph","stm","ltm","short-term-memory","long-term-memory","voyage","embeddings","agents-eco","agentic"],"repository":{"url":"git+https://github.com/agents-eco/agentic-memory.git","type":"git"},"description":"Graph-based agent memory — short-term and long-term memory with local or Voyage AI backends. Built for agents.eco.","maintainers":[{"name":"dudenpc","email":"ramankrishna10@gmail.com"}],"readme":"<p align=\"center\">\n  <img src=\"icon.png\" alt=\"Agentic Memory\" width=\"160\" />\n</p>\n\n<h1 align=\"center\">Agentic Memory</h1>\n\n<p align=\"center\">\n  <strong>Graph-based agent memory — short-term and long-term memory with local or Voyage AI backends.</strong><br/>\n  Built by <a href=\"https://agents.eco\">agents.eco</a> — the decentralized AI agent economy.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@agents-eco/agentic-memory\"><img src=\"https://img.shields.io/npm/v/@agents-eco/agentic-memory?style=flat-square\" alt=\"npm\" /></a>\n  <a href=\"https://github.com/agents-eco/agentic-memory/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" alt=\"MIT License\" /></a>\n  <a href=\"https://github.com/agents-eco/agentic-memory\"><img src=\"https://img.shields.io/github/stars/agents-eco/agentic-memory?style=flat-square\" alt=\"GitHub stars\" /></a>\n</p>\n\n```\nnpm install @agents-eco/agentic-memory\n```\n\n---\n\n## Why This Exists\n\nMost agent memory is either a flat conversation buffer or an opaque vector database. Neither captures how memory actually works.\n\nAgentic Memory is a **graph-based memory system** that separates short-term and long-term memory, with typed nodes, weighted relationships, decay, reinforcement, and hybrid search.\n\n- **Short-Term Memory (STM)** — Bounded working context. Recent items with automatic expiry. Fast keyword search.\n- **Long-Term Memory (LTM)** — Persistent graph with typed nodes (episodic, semantic, entity, goal, etc.) and weighted edges (causal, temporal, hierarchical). Supports decay and reinforcement.\n- **Two backends** — Local (zero dependencies, offline) or Voyage AI (high-quality neural embeddings).\n- **Graph traversal** — Find related memories by walking the graph, not just by vector similarity.\n- **Human-readable persistence** — Stored as JSON files you can inspect and version control.\n\n## Quick Start\n\n### Local Backend (no API key needed)\n\n```typescript\nimport { AgenticMemory } from \"@agents-eco/agentic-memory\";\n\nconst memory = new AgenticMemory({ backend: \"local\" });\n\n// Add memories\nawait memory.add(\"User's name is Alice\", \"semantic\", 0.8);\nawait memory.add(\"Alice prefers dark mode\", \"semantic\", 0.6);\nawait memory.addEpisode(\"User asked about the weather in NYC\");\nawait memory.addGoal(\"Help Alice plan her trip to Tokyo\");\n\n// Search\nconst results = await memory.search(\"What is the user's name?\");\nconsole.log(results[0].node.content); // \"User's name is Alice\"\n\n// Build context for LLM prompt injection\nconst context = await memory.buildContext(\"Tell me about Alice\");\nconsole.log(context);\n```\n\n### Voyage AI Backend (high-quality embeddings)\n\n```typescript\nimport { AgenticMemory } from \"@agents-eco/agentic-memory\";\n\nconst memory = new AgenticMemory({\n  backend: \"voyage\",\n  voyageApiKey: process.env.VOYAGE_API_KEY!,\n  voyageModel: \"voyage-3-lite\", // 512 dims, fast and cheap\n});\n\nawait memory.add(\"The project deadline is March 15th\", \"semantic\", 0.9);\nconst results = await memory.search(\"When is the deadline?\");\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    AgenticMemory                         │\n│                                                          │\n│  ┌─────────────────────┐  ┌──────────────────────────┐  │\n│  │   Short-Term Memory │  │    Long-Term Memory       │  │\n│  │                     │  │                           │  │\n│  │  Bounded buffer     │  │  ┌─────────────────────┐  │  │\n│  │  TTL-based expiry   │  │  │   Memory Graph      │  │  │\n│  │  Keyword search     │  │  │                     │  │  │\n│  │  Importance ranking │  │  │  Nodes (typed):     │  │  │\n│  │                     │  │  │  - episodic         │  │  │\n│  │  ┌───────────────┐  │  │  │  - semantic         │  │  │\n│  │  │ Consolidation │──┼──┼─▶│  - entity           │  │  │\n│  │  │ (STM → LTM)   │  │  │  │  - goal             │  │  │\n│  │  └───────────────┘  │  │  │  - observation       │  │  │\n│  │                     │  │  │  - procedural        │  │  │\n│  └─────────────────────┘  │  │  - emotional         │  │  │\n│                           │  │                     │  │  │\n│                           │  │  Edges (weighted):  │  │  │\n│                           │  │  - related_to       │  │  │\n│                           │  │  - caused_by        │  │  │\n│                           │  │  - leads_to         │  │  │\n│                           │  │  - part_of          │  │  │\n│                           │  │  - similar_to       │  │  │\n│                           │  │  - mentioned_in     │  │  │\n│                           │  └─────────────────────┘  │  │\n│                           │                           │  │\n│                           │  Decay + Reinforcement    │  │\n│                           │  Hybrid Search            │  │\n│                           │  Graph Traversal          │  │\n│                           └──────────────────────────┘  │\n│                                                          │\n│  ┌──────────────────┐  ┌──────────────────────────────┐  │\n│  │ Embedding Backend │  │     Storage Backend          │  │\n│  │                  │  │                              │  │\n│  │  Local (hash)    │  │  Local (JSON files)          │  │\n│  │  Voyage AI       │  │  Custom (implement iface)    │  │\n│  └──────────────────┘  └──────────────────────────────┘  │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Memory Types\n\n### Node Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `episodic` | Specific events and conversations | \"User asked about weather in NYC\" |\n| `semantic` | Facts, knowledge, extracted info | \"User's name is Alice\" |\n| `entity` | People, places, things | \"Alice\", \"Tokyo\", \"Project X\" |\n| `goal` | Objectives, tasks, intentions | \"Help user plan trip to Tokyo\" |\n| `observation` | Agent observations about the world | \"User seems frustrated today\" |\n| `procedural` | How-to, skills, patterns | \"To check weather, use the weather API\" |\n| `emotional` | Sentiment, preferences, reactions | \"User prefers concise responses\" |\n\n### Edge Types (Relations)\n\n| Relation | Description |\n|----------|-------------|\n| `related_to` | General association |\n| `caused_by` | Causal relationship |\n| `leads_to` | Sequential / temporal |\n| `part_of` | Hierarchical |\n| `contradicts` | Conflicting information |\n| `reinforces` | Supporting information |\n| `derived_from` | Extracted / inferred from |\n| `similar_to` | Semantic similarity |\n| `mentioned_in` | Entity mentioned in episode |\n| `precedes` / `follows` | Temporal ordering |\n\n## STM (Short-Term Memory)\n\nThe working context buffer. Bounded, fast, and ephemeral.\n\n```typescript\nimport { ShortTermMemory } from \"@agents-eco/agentic-memory\";\n\nconst stm = new ShortTermMemory({\n  capacity: 20,          // max items\n  ttlMs: 30 * 60 * 1000, // 30 min expiry\n});\n\nstm.add(\"User just asked about pricing\", \"episodic\", 0.7);\nstm.add(\"Current topic is billing\", \"observation\", 0.5);\n\n// Get recent context\nconst recent = stm.getRecent(5);\n\n// Search\nconst results = stm.search(\"pricing\");\n\n// Build context string for prompt injection\nconst context = stm.buildContext();\n```\n\n## LTM (Long-Term Memory)\n\nPersistent graph with decay, reinforcement, and hybrid search.\n\n```typescript\nimport { LongTermMemory } from \"@agents-eco/agentic-memory\";\nimport { LocalEmbedding } from \"@agents-eco/agentic-memory\";\n\nconst ltm = new LongTermMemory(\n  { decayRate: 0.01, minImportance: 0.1, maxNodes: 10000 },\n  new LocalEmbedding()\n);\n\n// Add memories\nconst fact = await ltm.add(\"Alice lives in New York\", \"semantic\", 0.7);\nconst entity = await ltm.add(\"Alice\", \"entity\", 0.6);\nltm.link(fact.id, entity.id, \"mentioned_in\");\n\n// Add facts with auto entity linking\nconst { node, entityNodes } = await ltm.addFact(\n  \"Alice is a software engineer at Acme Corp\",\n  [\"Alice\", \"Acme Corp\"]\n);\n\n// Search with graph traversal\nconst results = await ltm.search(\"Where does Alice work?\", {\n  limit: 5,\n  includeRelated: true,\n  traversalDepth: 2,\n});\n\n// Decay old memories\nltm.decay();\n```\n\n## Consolidation (STM to LTM)\n\nImportant short-term memories are promoted to long-term storage.\n\n```typescript\nconst memory = new AgenticMemory({ backend: \"local\" });\n\n// Add several memories to STM\nawait memory.add(\"User mentioned they like sushi\", \"semantic\", 0.7);\nawait memory.add(\"User asked about Tokyo restaurants\", \"episodic\", 0.5);\nawait memory.add(\"Random small talk\", \"episodic\", 0.2);\n\n// Consolidate important items to LTM\nconst count = await memory.consolidate(0.4); // min importance threshold\nconsole.log(`Consolidated ${count} memories to LTM`);\n// \"Random small talk\" stays in STM (too low importance)\n// The other two are now in the LTM graph with temporal links\n```\n\n## Hybrid Search\n\nCombines vector similarity, keyword matching, recency, and importance scoring.\n\n```typescript\nconst results = await memory.search(\"What does Alice like?\", {\n  limit: 5,\n  types: [\"semantic\", \"episodic\"],  // filter by type\n  minScore: 0.3,                     // minimum relevance\n  includeRelated: true,              // include graph neighbors\n  traversalDepth: 2,                 // how far to walk the graph\n  method: \"hybrid\",                  // vector + keyword + recency\n});\n\nfor (const r of results) {\n  console.log(`[${r.method}] (${r.score.toFixed(2)}) ${r.node.content}`);\n  if (r.related) {\n    for (const rel of r.related) {\n      console.log(`  └─ ${rel.content}`);\n    }\n  }\n}\n```\n\n## Persistence\n\nMemory is saved as JSON files you can inspect and version control.\n\n```typescript\nconst memory = new AgenticMemory({\n  backend: \"local\",\n  storageDir: \"./.agent/memory\",\n  namespace: \"my-agent\",  // creates graph-my-agent.json\n});\n\n// Auto-loads on first operation\nawait memory.add(\"Something important\", \"semantic\", 0.8);\n\n// Explicit save\nawait memory.save();\n\n// Stats\nconsole.log(memory.stats());\n// { stm: 1, ltm: { nodes: 1, edges: 0, byType: { semantic: 1 } } }\n```\n\n## Custom Backends\n\n### Custom Embedding Backend\n\n```typescript\nimport { EmbeddingBackend } from \"@agents-eco/agentic-memory\";\n\nclass OpenAIEmbedding implements EmbeddingBackend {\n  name = \"openai\";\n  dimension = 1536;\n\n  async embed(text: string): Promise<number[]> {\n    const res = await fetch(\"https://api.openai.com/v1/embeddings\", {\n      method: \"POST\",\n      headers: { Authorization: `Bearer ${apiKey}`, \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ model: \"text-embedding-3-small\", input: text }),\n    });\n    const data = await res.json();\n    return data.data[0].embedding;\n  }\n\n  async embedBatch(texts: string[]): Promise<number[][]> {\n    // Similar batch implementation\n  }\n}\n\nconst memory = new AgenticMemory({\n  backend: \"local\",\n  embedding: new OpenAIEmbedding(),\n});\n```\n\n### Custom Storage Backend\n\n```typescript\nimport { StorageBackend, SerializedGraph } from \"@agents-eco/agentic-memory\";\n\nclass RedisStorage implements StorageBackend {\n  name = \"redis\";\n\n  async save(graph: SerializedGraph): Promise<void> {\n    await redis.set(\"memory:graph\", JSON.stringify(graph));\n  }\n\n  async load(): Promise<SerializedGraph | null> {\n    const raw = await redis.get(\"memory:graph\");\n    return raw ? JSON.parse(raw) : null;\n  }\n\n  async exists(): Promise<boolean> {\n    return (await redis.exists(\"memory:graph\")) === 1;\n  }\n}\n\nconst memory = new AgenticMemory({\n  backend: \"local\",\n  storage: new RedisStorage(),\n});\n```\n\n## Integration with Open Agentic Framework\n\nUse as the memory backend for [@agents-eco/open-agentic-framework](https://github.com/agents-eco/open-agentic-framework):\n\n```typescript\nimport { Agent } from \"@agents-eco/open-agentic-framework\";\nimport { AgenticMemory } from \"@agents-eco/agentic-memory\";\n\nconst memory = new AgenticMemory({ backend: \"local\" });\n\n// Implement the MemoryStore interface\nconst memoryStore = {\n  async add(entry) {\n    const { stmEntry } = await memory.add(entry.content, entry.type as any, 0.5);\n    return { id: stmEntry.id, content: entry.content, type: entry.type, timestamp: stmEntry.createdAt };\n  },\n  async search(query, limit) {\n    const results = await memory.search(query, { limit });\n    return results.map((r) => ({\n      id: r.node.id,\n      content: r.node.content,\n      type: r.node.type,\n      timestamp: r.node.createdAt,\n    }));\n  },\n  async list(limit) {\n    const entries = memory.stm.getRecent(limit);\n    return entries.map((e) => ({\n      id: e.id,\n      content: e.content,\n      type: e.type,\n      timestamp: e.createdAt,\n    }));\n  },\n  async clear() {\n    await memory.clear();\n  },\n};\n\nconst agent = new Agent({\n  name: \"memory-agent\",\n  systemPrompt: \"You remember everything.\",\n  provider: { name: \"venice\", apiKey: \"...\", baseUrl: \"https://api.venice.ai/api/v1\", defaultModel: \"qwen3-4b\" },\n  memory: memoryStore,\n});\n```\n\n## API Reference\n\n### `AgenticMemory`\n\n| Method | Description |\n|--------|-------------|\n| `add(content, type?, importance?, metadata?)` | Add to STM (and LTM if important) |\n| `addEpisode(content, importance?)` | Add episodic memory with temporal linking |\n| `addFact(content, entities?, importance?)` | Add semantic memory with entity extraction |\n| `addObservation(content, importance?)` | Add an observation |\n| `addGoal(content, importance?)` | Add a goal |\n| `link(sourceId, targetId, relation, weight?)` | Create a relationship in LTM |\n| `search(query, options?)` | Hybrid search across STM + LTM |\n| `buildContext(query?)` | Build context string for prompt injection |\n| `consolidate(minImportance?)` | Promote important STM entries to LTM |\n| `decay()` | Apply decay to LTM nodes |\n| `save()` | Persist to storage |\n| `load()` | Load from storage |\n| `clear()` | Clear all memory |\n| `stats()` | Get memory statistics |\n\n### `SearchOptions`\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `limit` | `number` | `5` | Max results |\n| `types` | `MemoryNodeType[]` | all | Filter by node type |\n| `minScore` | `number` | `0.0` | Minimum relevance score |\n| `includeRelated` | `boolean` | `false` | Include graph neighbors |\n| `traversalDepth` | `number` | `1` | Graph walk depth |\n| `method` | `\"vector\" \\| \"keyword\" \\| \"hybrid\"` | `\"hybrid\"` | Search method |\n\n## Contributing\n\nWe welcome contributions. This project is early and there is room to shape its direction.\n\n- **Add a storage backend** — SQLite, Redis, PostgreSQL, S3\n- **Add an embedding backend** — OpenAI, Cohere, local transformers\n- **Improve search** — better scoring, re-ranking, query expansion\n- **Visualization** — graph visualization tools for debugging memory\n- **Report issues** — bug reports and feature requests help us prioritize\n\n## License\n\nMIT — [agents.eco](https://agents.eco)\n\n---\n\n<p align=\"center\">\n  Built by <a href=\"https://agents.eco\">agents.eco</a> — the decentralized AI agent economy.\n</p>\n","readmeFilename":"README.md"}