@aitytech/agentkits-memory 1.0.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AityTech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,34 +1,161 @@
-# @agentkits/memory
-
-Project-scoped memory system for AgentKits with SQLite storage and optional HNSW vector search.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aitytech/agentkits-memory/main/assets/logo.svg" alt="AgentKits Logo" width="80" height="80">
+</p>
+
+<h1 align="center">AgentKits Memory</h1>
+
+<p align="center">
+  <em>by <strong>AityTech</strong></em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@aitytech/agentkits-memory"><img src="https://img.shields.io/npm/v/@aitytech/agentkits-memory.svg" alt="npm"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+  <img src="https://img.shields.io/badge/Claude_Code-Compatible-blueviolet" alt="Claude Code">
+  <img src="https://img.shields.io/badge/Cursor-Compatible-blue" alt="Cursor">
+  <img src="https://img.shields.io/badge/Copilot-Compatible-green" alt="Copilot">
+  <img src="https://img.shields.io/badge/Windsurf-Compatible-cyan" alt="Windsurf">
+  <img src="https://img.shields.io/badge/Cline-Compatible-orange" alt="Cline">
+</p>
+
+<p align="center">
+  <strong>Persistent Memory System for AI Coding Assistants via MCP</strong>
+</p>
+
+<p align="center">
+  <em>Fast. Local. Zero external dependencies.</em>
+</p>
+
+<p align="center">
+  Store decisions, patterns, errors, and context that persists across sessions.<br>
+  No cloud. No API keys. No setup. Just works.
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#web-viewer">Web Viewer</a> •
+  <a href="#features">Features</a> •
+  <a href="#agentkits-ecosystem">Ecosystem</a> •
+  <a href="https://agentkits.net">agentkits.net</a>
+</p>
+
+---
 
 ## Features
 
-- **Project-Scoped Storage**: Memory is stored in `.claude/memory/memory.db` within your project
-- **SQLite + WASM**: Cross-platform compatibility (Windows, macOS, Linux)
-- **Optional Vector Search**: HNSW indexing for semantic similarity search
-- **Session Tracking**: Track Claude Code sessions with checkpoints
-- **Migration Support**: Migrate from existing `.claude/memory/*.md` files
-- **Backward Compatible**: Export to markdown for git-friendly backups
+| Feature | Benefit |
+|---------|---------|
+| **100% Local** | All data stays on your machine. No cloud, no API keys, no accounts |
+| **Blazing Fast** | Native SQLite (better-sqlite3) = instant queries, zero latency |
+| **Zero Config** | Works out of the box. No database setup required |
+| **Cross-Platform** | Windows, macOS, Linux - same code, same speed |
+| **MCP Server** | `memory_save`, `memory_search`, `memory_recall`, `memory_list`, `memory_status` |
+| **Web Viewer** | Browser UI to view, add, edit, delete memories |
+| **Vector Search** | Optional HNSW semantic similarity (no external service) |
+| **Auto-Capture** | Hooks for session context, tool usage, summaries |
+
+---
+
+## Web Viewer
 
-## Installation
+View and manage your memories through a modern web interface.
 
 ```bash
-npm install @agentkits/memory
-# or
-pnpm add @agentkits/memory
+npx agentkits-memory-web
 ```
 
+Then open **http://localhost:1905** in your browser.
+
+### Memory List
+
+Browse all stored memories with search and namespace filtering.
+
+![Memory List](https://raw.githubusercontent.com/aitytech/agentkits-memory/main/assets/agentkits-memory-memory-list.png)
+
+### Add Memory
+
+Create new memories with key, namespace, type, content, and tags.
+
+![Add Memory](https://raw.githubusercontent.com/aitytech/agentkits-memory/main/assets/agentkits-memory-add-memory.png)
+
+### Memory Details
+
+View full memory details with edit and delete options.
+
+![Memory Detail](https://raw.githubusercontent.com/aitytech/agentkits-memory/main/assets/agentkits-memory-memory-detail.png)
+
+---
+
 ## Quick Start
 
+### 1. Install
+
+```bash
+npm install @aitytech/agentkits-memory
+```
+
+### 2. Configure MCP Server
+
+Add to your `.mcp.json` (or `.claude/.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["agentkits-memory-server"]
+    }
+  }
+}
+```
+
+### 3. Use Memory Tools
+
+Once configured, your AI assistant can use these tools:
+
+| Tool | Description |
+|------|-------------|
+| `memory_save` | Save decisions, patterns, errors, or context |
+| `memory_search` | Search memories using semantic similarity |
+| `memory_recall` | Recall everything about a specific topic |
+| `memory_list` | List recent memories |
+| `memory_status` | Check memory system status |
+
+---
+
+## CLI Commands
+
+```bash
+# Start MCP server
+npx agentkits-memory-server
+
+# Start web viewer (port 1905)
+npx agentkits-memory-web
+
+# View stored memories (terminal)
+npx agentkits-memory-viewer
+
+# Save memory from CLI
+npx agentkits-memory-save "Use JWT with refresh tokens" --category pattern --tags auth,security
+
+# Setup hooks for auto-capture
+npx agentkits-memory-setup
+```
+
+---
+
+## Programmatic Usage
+
 ```typescript
-import { ProjectMemoryService } from '@agentkits/memory';
+import { ProjectMemoryService } from '@aitytech/agentkits-memory';
 
-// Initialize memory for current project
-const memory = new ProjectMemoryService('.claude/memory');
+const memory = new ProjectMemoryService({
+  baseDir: '.claude/memory',
+  dbFilename: 'memory.db',
+});
 await memory.initialize();
 
-// Store an entry
+// Store a memory
 await memory.storeEntry({
   key: 'auth-pattern',
   content: 'Use JWT with refresh tokens for authentication',
@@ -36,11 +163,11 @@ await memory.storeEntry({
   tags: ['auth', 'security'],
 });
 
-// Query entries
-const patterns = await memory.query({
+// Query memories
+const results = await memory.query({
   type: 'hybrid',
   namespace: 'patterns',
-  tags: ['auth'],
+  content: 'authentication',
   limit: 10,
 });
 
@@ -48,84 +175,111 @@ const patterns = await memory.query({
 const entry = await memory.getByKey('patterns', 'auth-pattern');
 ```
 
-## Session Management
+---
 
-```typescript
-// Start a new session
-await memory.startSession();
+## Auto-Capture Hooks
 
-// Create checkpoints during work
-await memory.checkpoint('Completed authentication setup');
-await memory.checkpoint('Added user registration');
+The package includes hooks for automatically capturing AI coding sessions:
 
-// End session with summary
-await memory.endSession('Successfully implemented auth flow');
+| Hook | Trigger | Action |
+|------|---------|--------|
+| `context` | Session Start | Injects previous session context |
+| `session-init` | First User Prompt | Initializes session record |
+| `observation` | After Tool Use | Captures tool usage |
+| `summarize` | Session End | Generates session summary |
 
-// Get recent sessions
-const sessions = await memory.getRecentSessions(5);
+Setup hooks:
+```bash
+npx agentkits-memory-setup
 ```
 
-## Migration from Markdown
+Or manually copy `hooks.json` to your project:
+```bash
+cp node_modules/@aitytech/agentkits-memory/hooks.json .claude/hooks.json
+```
 
-```typescript
-// Migrate existing .claude/memory/*.md files
-const result = await memory.migrateFromMarkdown();
-console.log(result.summary);
-// Output: "Migrated 24/24 entries"
+---
+
+## Memory Categories
+
+| Category | Use Case |
+|----------|----------|
+| `decision` | Architecture decisions, ADRs |
+| `pattern` | Reusable code patterns |
+| `error` | Error solutions and fixes |
+| `context` | Project context and facts |
+| `observation` | Session observations |
+
+---
+
+## Storage
+
+Memories are stored in `.claude/memory/memory.db` within your project directory.
+
+```
+.claude/memory/
+├── memory.db          # SQLite database
+└── memory.db-wal      # Write-ahead log (temp)
 ```
 
-## Semantic Search (Optional)
+---
+
+## CJK Language Support
+
+AgentKits Memory has **automatic CJK support** for Chinese, Japanese, and Korean text search.
+
+### Zero Configuration
+
+When `better-sqlite3` is installed (default), CJK search works automatically:
 
 ```typescript
-import { createEmbeddingMemory } from '@agentkits/memory';
-
-// Create memory with embedding support
-const memory = createEmbeddingMemory(
-  '.claude/memory',
-  async (text) => {
-    // Your embedding function (e.g., OpenAI, local model)
-    return await embeddings.embed(text);
-  },
-  384 // dimensions
-);
+import { ProjectMemoryService } from '@aitytech/agentkits-memory';
 
+const memory = new ProjectMemoryService('.claude/memory');
 await memory.initialize();
 
-// Semantic search
-const similar = await memory.semanticSearch('how to authenticate users', 5);
+// Store CJK content
+await memory.storeEntry({
+  key: 'auth-pattern',
+  content: '認証機能の実装パターン - JWT with refresh tokens',
+  namespace: 'patterns',
+});
+
+// Search in Japanese, Chinese, or Korean - it just works!
+const results = await memory.query({
+  type: 'hybrid',
+  content: '認証機能',
+});
 ```
 
-## Export to Markdown
+### How It Works
+
+- **Native SQLite**: Uses `better-sqlite3` for maximum performance
+- **Trigram tokenizer**: FTS5 with trigram creates 3-character sequences for CJK matching
+- **Smart fallback**: Short CJK queries (< 3 chars) automatically use LIKE search
+- **BM25 ranking**: Relevance scoring for search results
+
+### Advanced: Japanese Word Segmentation
+
+For advanced Japanese with proper word segmentation, optionally use lindera:
 
 ```typescript
-// Export namespace to markdown (for git)
-await memory.exportToMarkdown('patterns');
-// Creates: .claude/memory/patterns.md
+import { createJapaneseOptimizedBackend } from '@aitytech/agentkits-memory';
 
-// Export all namespaces
-const files = await memory.exportAllToMarkdown();
+const backend = createJapaneseOptimizedBackend({
+  databasePath: '.claude/memory/memory.db',
+  linderaPath: './path/to/liblindera_sqlite.dylib',
+});
 ```
 
-## Default Namespaces
-
-The memory system uses these default namespaces (matching existing `.md` file structure):
+Requires [lindera-sqlite](https://github.com/lindera/lindera-sqlite) build.
 
-| Namespace | Type | Purpose |
-|-----------|------|---------|
-| `context` | semantic | Project context and facts |
-| `active-context` | episodic | Current work focus |
-| `session-state` | episodic | Session handoff notes |
-| `progress` | episodic | Feature tracking |
-| `patterns` | semantic | Reusable code patterns |
-| `decisions` | procedural | ADRs and decisions |
-| `errors` | procedural | Error solutions |
+---
 
 ## API Reference
 
 ### ProjectMemoryService
 
-#### Configuration
-
 ```typescript
 interface ProjectMemoryConfig {
   baseDir: string;              // Default: '.claude/memory'
@@ -136,115 +290,79 @@ interface ProjectMemoryConfig {
   cacheEnabled: boolean;        // Default: true
   cacheSize: number;            // Default: 1000
   cacheTtl: number;             // Default: 300000 (5 min)
-  autoPersistInterval: number;  // Default: 10000 (10 sec)
-  maxEntries: number;           // Default: 100000
-  verbose: boolean;             // Default: false
 }
 ```
 
-#### Methods
+### Methods
 
 | Method | Description |
 |--------|-------------|
 | `initialize()` | Initialize the memory service |
 | `shutdown()` | Shutdown and persist changes |
-| `store(entry)` | Store a memory entry |
-| `storeEntry(input)` | Store from simple input |
+| `storeEntry(input)` | Store a memory entry |
 | `get(id)` | Get entry by ID |
 | `getByKey(namespace, key)` | Get entry by namespace and key |
 | `update(id, update)` | Update an entry |
 | `delete(id)` | Delete an entry |
 | `query(query)` | Query entries with filters |
-| `search(embedding, options)` | Vector similarity search |
-| `semanticSearch(content, k)` | Search by content string |
+| `semanticSearch(content, k)` | Semantic similarity search |
 | `count(namespace?)` | Count entries |
 | `listNamespaces()` | List all namespaces |
-| `clearNamespace(namespace)` | Clear a namespace |
-| `startSession()` | Start new session |
-| `checkpoint(description)` | Create checkpoint |
-| `endSession(summary?)` | End current session |
-| `migrateFromMarkdown()` | Migrate from .md files |
-| `exportToMarkdown(namespace)` | Export to markdown |
 | `getStats()` | Get statistics |
-| `healthCheck()` | Health check |
 
-## Architecture
+---
 
-```
-.claude/memory/
-├── memory.db          # SQLite database (primary storage)
-├── memory.db-wal      # Write-ahead log (temp)
-└── exports/           # Optional markdown exports
-    ├── patterns.md
-    ├── decisions.md
-    └── ...
-```
+## Requirements
 
-## Performance
+- Node.js >= 18.0.0
+- MCP-compatible AI coding assistant
 
-| Operation | Time |
-|-----------|------|
-| Store entry | <5ms |
-| Get by ID | <2ms (cached: <0.1ms) |
-| Query (100 results) | <10ms |
-| Vector search (10k entries) | <5ms (with HNSW) |
-| Migration (100 files) | <2s |
+---
 
-## Claude Code Hooks (Auto-Capture)
+## AgentKits Ecosystem
 
-The memory package includes a lightweight hook system for automatically capturing Claude Code sessions.
+**AgentKits Memory** is part of the AgentKits ecosystem by AityTech - tools that make AI coding assistants smarter.
 
-### Quick Setup
+| Product | Description | Link |
+|---------|-------------|------|
+| **AgentKits Engineer** | 28 specialized agents, 100+ skills, enterprise patterns | [GitHub](https://github.com/aitytech/agentkits-engineer) |
+| **AgentKits Marketing** | AI-powered marketing content generation | [GitHub](https://github.com/aitytech/agentkits-marketing) |
+| **AgentKits Memory** | Persistent memory for AI assistants (this package) | [npm](https://www.npmjs.com/package/@aitytech/agentkits-memory) |
 
-1. Install the package globally or in your project:
-```bash
-npm install -g @agentkits/memory
-# or
-npm install @agentkits/memory
-```
+<p align="center">
+  <a href="https://agentkits.net">
+    <img src="https://img.shields.io/badge/Visit-agentkits.net-blue?style=for-the-badge" alt="agentkits.net">
+  </a>
+</p>
 
-2. Copy the hooks configuration to your project:
-```bash
-cp node_modules/@agentkits/memory/hooks.json .claude/hooks.json
-```
-
-3. Claude Code will now automatically:
-   - Inject previous session context on start
-   - Track all tool usage during the session
-   - Generate session summaries on exit
-
-### Hook Events
-
-| Event | Trigger | Action |
-|-------|---------|--------|
-| `context` | SessionStart | Injects memory context |
-| `session-init` | UserPromptSubmit | Initializes session record |
-| `observation` | PostToolUse | Captures tool usage |
-| `summarize` | Stop | Generates session summary |
+---
 
-### Manual Hook Usage
+## Star History
 
-```typescript
-import { createContextHook, createObservationHook } from '@agentkits/memory/hooks';
-
-// Create hook handlers
-const contextHook = createContextHook(process.cwd());
-const observationHook = createObservationHook(process.cwd());
+<a href="https://star-history.com/#aitytech/agentkits-memory&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=aitytech/agentkits-memory&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=aitytech/agentkits-memory&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=aitytech/agentkits-memory&type=Date" />
+ </picture>
+</a>
 
-// Execute hooks
-const result = await contextHook.execute(input);
-```
+---
 
-### Database Location
+## License
 
-Hook data is stored in `.claude/memory/hooks.db` within your project directory.
+MIT
 
-### Skipped Tools
+---
 
-Internal tools that are not captured:
-- `TodoWrite`, `TodoRead`
-- `AskFollowupQuestion`, `AttemptCompletion`
+<p align="center">
+  <strong>Give your AI assistant memory that persists.</strong>
+</p>
 
-## License
+<p align="center">
+  <em>AgentKits Memory by AityTech</em>
+</p>
 
-MIT - Based on claude-flow memory system (AGPL-3.0)
+<p align="center">
+  Star this repo if it helps your AI remember.
+</p>

package/assets/logo.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40">
+  <defs>
+    <linearGradient id="logoGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#2563EB"/>
+      <stop offset="100%" style="stop-color:#3B82F6"/>
+    </linearGradient>
+  </defs>
+  <!-- Background -->
+  <rect width="40" height="40" rx="8" fill="url(#logoGrad)"/>
+  <!-- Central hub -->
+  <circle cx="20" cy="20" r="5" fill="#fff"/>
+  <!-- Nodes -->
+  <circle cx="20" cy="9" r="3" fill="#fff"/>
+  <circle cx="20" cy="31" r="3" fill="#fff"/>
+  <circle cx="9" cy="20" r="3" fill="#fff"/>
+  <circle cx="31" cy="20" r="3" fill="#fff"/>
+  <!-- Connections -->
+  <line x1="20" y1="15" x2="20" y2="12" stroke="#fff" stroke-width="1.5" stroke-linecap="round"/>
+  <line x1="20" y1="25" x2="20" y2="28" stroke="#fff" stroke-width="1.5" stroke-linecap="round"/>
+  <line x1="15" y1="20" x2="12" y2="20" stroke="#fff" stroke-width="1.5" stroke-linecap="round"/>
+  <line x1="25" y1="20" x2="28" y2="20" stroke="#fff" stroke-width="1.5" stroke-linecap="round"/>
+  <!-- Center dot -->
+  <circle cx="20" cy="20" r="2" fill="#2563EB"/>
+</svg>