@kernel.chat/memory-tiers - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

README.md

+# @kernel.chat/memory-tiers
+
+> Three-tier generative memory for AI agents: observations → reflections →
+> identity. Based on Stanford's *Generative Agents* paper. **Zero LLM calls.**
+
+Part of the [kernel.chat](https://kernel.chat) open-source stack. Used by
+`@kernel.chat/kbot` to give specialist agents a persistent sense of what
+they've seen, what it means, and who they're becoming over time.
+
+## Why three tiers
+
+Single-tier memory (a flat log of everything) doesn't scale: every query
+re-scans the whole history. Two-tier memory (raw + summary) loses the why
+behind the what.
+
+This package implements three tiers, each derived from the one below:
+
+1. **Observations** — raw events the agent encountered (user asked X,
+   tool returned Y, error Z occurred). Append-only.
+2. **Reflections** — synthesized patterns across observations
+   ("the user often asks about Polymarket on Fridays"). Generated
+   periodically by deterministic summarization rules.
+3. **Identity** — durable traits that emerge from reflections over time
+   ("treats every regulated-industry question as audit-grade by default").
+   The slowest-changing layer; the agent's working self-model.
+
+The synthesis between tiers is rule-based and deterministic — no LLM call.
+This makes it cheap to run continuously and replayable for audit.
+
+## Install
+
+```bash
+npm install @kernel.chat/memory-tiers
+```
+
+## Usage
+
+```ts
+import { MemorySystem } from '@kernel.chat/memory-tiers'
+
+const memory = new MemorySystem({
+  // Optional config — thresholds for synthesis cadence, retention, etc.
+})
+
+// Tier 1 — feed observations as they happen.
+memory.observe('User asked about Polymarket Trump 2028 odds', 'query', {
+  threadId: 'abc',
+})
+memory.observe('Tool call: polymarket_query succeeded in 312ms', 'tool')
+
+// Tier 2 — periodically synthesize reflections.
+const reflections = memory.synthesize()
+
+// Tier 3 — let reflections accumulate into identity.
+const identity = memory.evolve()
+
+// Read each tier back.
+const observations = memory.getObservations('query')
+const allReflections = memory.getReflections()
+const traits = memory.getIdentity()
+
+// Persist across runs.
+memory.save('./memory.json')
+memory.load('./memory.json')
+
+// Inspect.
+console.log(memory.summary())
+console.log(memory.getStats())
+```
+
+## Public API
+
+| Export | Shape |
+|---|---|
+| `MemorySystem` | Main class — `observe`, `getObservations`, `synthesize`, `getReflections`, `evolve`, `getIdentity`, `toJSON`/`fromJSON`, `save`/`load`, `getStats`, `summary` |
+| `Observation` | Tier 1 entry |
+| `ObservationCategory` | Union of categories (query, tool, error, etc.) |
+| `Reflection` | Tier 2 entry |
+| `IdentityTrait` | Tier 3 entry |
+| `MemoryState` | Serialized state shape |
+| `MemoryConfig` | Constructor config |
+
+## Status
+
+**v1.0.x — production use inside `@kernel.chat/kbot`; light external test
+coverage.** The three-tier model has been running in kbot since early 2026.
+The public API is stable. External test suite expanded in v1.1.
+
+File issues at [github.com/isaacsight/kernel](https://github.com/isaacsight/kernel/issues)
+if you hit edge cases outside the kernel.chat usage path.
+
+## Related packages
+
+| Package | Discipline |
+|---|---|
+| [@kernel.chat/kbot](https://www.npmjs.com/package/@kernel.chat/kbot) | The agent itself |
+| [@kernel.chat/prompt-evolver](https://www.npmjs.com/package/@kernel.chat/prompt-evolver) | Prompt self-optimization from traces |
+| [@kernel.chat/skill-router](https://www.npmjs.com/package/@kernel.chat/skill-router) | Bayesian routing across specialists |
+| [@kernel.chat/tool-forge](https://www.npmjs.com/package/@kernel.chat/tool-forge) | Runtime tool creation |
+
+See [`docs/agentic-engineering.md`](https://github.com/isaacsight/kernel/blob/main/docs/agentic-engineering.md)
+for the field map this package sits inside.
+
+## License
+
+MIT.

package.json

 {
   "name": "@kernel.chat/memory-tiers",
-  "version": "1.0.0",
-  "description": "Three-tier generative memory for AI agents: observations → reflections → identity. Based on Stanford's Generative Agents paper. Zero LLM calls.",
+  "version": "1.0.1",
+  "description": "Three-tier generative memory for AI agents: observations \u2192 reflections \u2192 identity. Based on Stanford's Generative Agents paper. Zero LLM calls.",
   "type": "module",
@@ -17,6 +17,15 @@ "main": "./dist/index.js",
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "keywords": [
-    "ai-agent", "memory", "generative-agents", "three-tier",
-    "observations", "reflections", "identity", "llm", "kbot"
+    "ai-agent",
+    "memory",
+    "generative-agents",
+    "three-tier",
+    "observations",
+    "reflections",
+    "identity",
+    "llm",
+    "kbot"
   ],
@@ -33,2 +42,2 @@ "license": "MIT",
   }
-}
+}

Fixed alerts

Deprecated

Maintenance

The maintainer of the package marked it as deprecated. This could indicate that a single version should not be used, or that the package is no longer maintained and any new vulnerabilities will not be fixed.

Found 1 instance in 1 package

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

35814

12.17%

Number of package files

6

20%

Number of medium maintenance alerts

0

-100%

Number of medium quality alerts

0

-100%

Number of lines in readme file

107

Infinity%

No dependency changes