@memstack/core 0.7.2 → 0.8.0

package/README.md

@@ -1,18 +1,24 @@
 # MemStack
 
-> Implementation priority is maintained in the [canonical roadmap](docs/ROADMAP.md).
-
 > The open-source memory layer for AI agents — store, retrieve, summarize, and prune.
 
 [![npm version](https://img.shields.io/npm/v/@memstack/core)](https://www.npmjs.com/package/@memstack/core)
+[![skills.sh](https://skills.sh/b/isiomaC/memstack)](https://skills.sh/isiomaC/memstack)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-%40memstack%2Fmcp-blueviolet)](https://registry.modelcontextprotocol.io/?q=io.github.isiomaC%2Fmemstack)
 [![CI](https://github.com/isiomaC/memstack/actions/workflows/ci.yml/badge.svg)](https://github.com/isiomaC/memstack/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP Reference](https://img.shields.io/badge/MCP-LLM%20Reference-blue)](https://gitmcp.io/isiomaC/memstack)
 
 ```bash
+# Use MemStack in your application
 npm install @memstack/core
+
+# Give your coding agent the MemStack skill
+npx skills add isiomaC/memstack
 ```
 
+`@memstack/core` is the runtime SDK; the Agent Skill teaches compatible coding agents how to integrate and operate MemStack correctly.
+
 **The problem:** AI agents forget. Every interaction starts from zero. You either stuff everything into the context window (expensive, slow, degrades output quality) or the agent has no memory of past conversations.
 
 **What MemStack does:** A persistent memory pipeline that lives between your agent and the LLM. It stores every interaction, retrieves only what's relevant, summarizes old memories to save tokens, and prunes stale ones automatically. One method call, no infrastructure required.
@@ -86,6 +92,32 @@ Think of it as the open-source alternative to [Mem0](https://mem0.ai/) — plugg
 
 ## Quick Start
 
+### Claude Code and Codex
+
+Persistent memory across agent harnesses: what you tell Claude Code, Codex
+recalls in the same project, and the reverse.
+
+```bash
+npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0  # MemStack never installs storage drivers for you
+memstack init                  # choose an LLM provider and a store
+memstack connect claude-code
+memstack connect codex
+```
+
+Memories are scoped to the git repository by its first commit, so clones,
+worktrees, renamed remotes, and moved folders all share them (pin a name with
+`memstack project pin <id>`). `connect` also installs a session-start hook, so every
+new session starts with the project's key memories (Codex asks you to approve
+it once with `/hooks`). For Codex, `connect` also adds a marked block to
+`~/.codex/AGENTS.md` so it saves memories when asked. Recall runs locally
+without an LLM call, and any
+supported store works: swap `better-sqlite3` for `postgres@^3.4.9` or
+`ioredis@^5.11.1` and pick that store in `memstack init`. `memstack status`,
+`memstack doctor`, and `memstack memories` show what is connected and
+stored. See [the harness profile](docs/MCP_SETUP.md#harness-profile-claude-code-and-codex).
+
+### As a library
+
 ```bash
 npm install @memstack/core
 ```
@@ -114,7 +146,7 @@ import { MemStack, OpenAILLMAdapter, InMemoryStorageAdapter } from "@memstack/co
 const llm = new OpenAILLMAdapter({
   apiKey: process.env.DEEPSEEK_API_KEY!,
   baseURL: "https://api.deepseek.com/v1",
-  defaultModel: "deepseek-chat",
+  defaultModel: "deepseek-flash",
 });
 
 const memstack = new MemStack({
@@ -201,7 +233,7 @@ Every agent interaction becomes a `Memory` with metadata that controls how it's
 interface Memory {
   id: string;
   actorId: string;               // Who this memory belongs to (user ID, agent ID, session ID)
-  memoryType: MemoryType;        // "interaction" | "summary" | "observation" | "fact" | "reflection"
+  memoryType: MemoryType;        // "interaction" | "summary" | "observation" | "fact" | "reflection" | "preference" | "decision" | "instruction"
   content: string;               // The actual text
   importance: number;            // 0-1 — higher = survives pruning, ranks higher in retrieval
   emotionalValence: number;      // -1 to 1 — for tone-aware retrieval
@@ -497,6 +529,9 @@ const userCount = await ms.memory.count({ actorId: "user-42" });
 | `observation` | Passive knowledge — facts, documents, things the agent knows but didn't interact with. | "Company refund policy is 30 days from purchase." |
 | `fact` | Verified knowledge — discrete truths the agent has confirmed. | "The user's subscription tier is Enterprise." |
 | `reflection` | Self-generated insight — the agent thinking about its own experiences. | "I tend to over-explain billing policies — should be more concise." |
+| `preference` | How the user likes things done. | "Prefer small pull requests with one concern each." |
+| `decision` | A choice made, ideally with its reason. | "Chose Hono over Express for edge runtime support." |
+| `instruction` | A standing rule to follow. | "Never commit directly to main." |
 
 Types control retrieval behavior — `compileContext()` treats `interaction` and `summary` differently from `observation`. Use types to separate "what happened" from "what I know."
 
@@ -526,6 +561,29 @@ await ms.memory.retrieve({ actorId: "x", query: "login bug", strategy: "hybrid"
 - Use `semantic` for RAG, document search, knowledge base queries
 - Use `hybrid` for most agent memory — it balances meaning with significance
 
+### Keyword recall on any storage adapter
+
+`LexicalRetriever` answers natural questions without embeddings or an LLM
+call, and behaves the same on every storage adapter. It loads the memories
+in the given actors through `retrieve()`, then ranks them in MemStack with
+BM25 over content and tags, with stemming and prefix matching. When nothing
+matches, it returns the most important memories instead.
+
+```typescript
+import { LexicalRetriever } from "@memstack/core";
+
+const retriever = new LexicalRetriever(storage);
+const { hits, fallback } = await retriever.recall({
+  actorIds: ["project:abc", "global"], // Searched together
+  query: "What framework does this project use?",
+  limit: 10,                           // Max results
+  maxChars: 8000,                      // Max total content; the top hit is always returned
+});
+```
+
+Up to 2,000 memories per actor are ranked (`candidateLimit`). Only returned
+memories are marked as accessed.
+
 ---
 
 ## Embeddings
@@ -927,6 +985,19 @@ const ms = new MemStack({
 
 Implement `StorageProvider` for any database. The interface is 9 methods. See the reference section above for the full contract.
 
+Optional members, none of them required:
+
+- `capabilities: { multiProcess?, textSearch? }` declares whether several
+  processes can share the store safely and whether `search()` is native.
+- `search(query)` provides native full-text search. `LexicalRetriever` uses
+  it when `textSearch` is declared and ranks memories itself otherwise.
+- `retrieve()` should honor `touch: false` by returning memories without
+  marking them as accessed.
+
+`SQLiteStorageAdapter` enables WAL and a 5-second busy timeout so several
+processes can share one database file. Set `walMode: false` or
+`busyTimeoutMs` to change this.
+
 ### Custom LLM / Embedding
 
 Implement `LLMProvider` or `EmbeddingProvider` for any service: