# dsh-memory-plugin
> Intelligent memory system for DSH - Track user preferences, tool usage, and project context to provide personalized recommendations
[](LICENSE)
[](package.json)
[](https://github.com/deepseek-ai/deepseek-harness)
[็ฎไฝไธญๆ](README.md) | **English**
---
## ๐ Overview
dsh-memory-plugin is an intelligent memory system plugin designed for DeepSeek Harness (DSH). It automatically learns user habits, remembers preferences, tracks project context, and provides personalized smart recommendations based on this data, significantly improving development efficiency and work experience.
## โจ Key Features
- **๐ฏ Smart Recommendation Engine** - Automatically recommends the best models, Agents, and tool configurations based on historical data
- **๐ Tool Usage Tracking** - Automatically records usage frequency of common tools (read, write, edit, glob, grep, etc.)
- **๐ค Preference Memory** - Remembers preferred Agents, LLMs, language settings, and coding styles
- **๐ Project Context** - Tracks active projects, access history, and project tags
- **๐ฌ Session History** - Records discussion topics, completed tasks, and work patterns
- **๐พ Persistent Storage** - Local JSON storage with auto-save, import, and export support
- **๐ Privacy Protection** - Fully local storage, no cloud sync, complete user control over data
- **๐จ Web Viewer** - Beautiful visualization interface for intuitive memory data display
## ๐ Quick Start
### One-Click Install (Recommended)
**For Windows users:**
```bash
# Option 1: Double-click
install.bat
# Option 2: PowerShell
.\install.ps1
```
The script will automatically:
- ๐ Find DSH configuration directory
- ๐ฆ Copy or create symbolic link
- โ
Verify installation result
### Manual Installation
#### Option 1: As a Local Plugin
```bash
# Clone the repository
git clone https://github.com/ly028716/dsh-memory-plugin.git
# Add to DSH profile directory
cd ~/.dsh/profiles
dsh plugin --profile add /path/to/dsh-memory-plugin
```
#### Option 2: Install from npm (Recommended)
```bash
dsh plugin --profile add @ly028716/dsh-memory-plugin
```
#### Option 3: Direct Code Integration
```javascript
const memoryPlugin = require('./dsh-memory-plugin');
// Create DSH context
const ctx = {
_services: {},
effect(fn) { /* ... */ },
provide(name, service) {
this._services[name] = service;
}
};
// Apply plugin
memoryPlugin.apply(ctx, {
storagePath: '.dsh-memory.json',
trackToolCalls: true,
enableRecommendations: true
});
```
Initialization is asynchronous. Await `ctx.memory.ready` before the first read that needs persisted data; write APIs wait for initialization automatically:
```javascript
await ctx.memory.ready;
const stats = ctx.memory.getStats();
```
### Basic Usage
The plugin does not collect data automatically by default. Startup also does not create a memory file or increment the session count. The four `track*` toggles control automatic collection only; explicit `ctx.memory` API calls still write and persist data:
```javascript
// Get smart recommendations
const recs = ctx.memory.getRecommendations('coding');
// Set preferences
await ctx.memory.setPreference('defaultModel', 'qwen3.7-plus');
await ctx.memory.setPreference('preferredAgents', ['coding-assistant']);
// Record sessions
await ctx.memory.recordTopic('implement authentication');
await ctx.memory.addProject({
path: '/projects/my-app',
name: 'my-app',
tags: ['react', 'typescript']
});
// View statistics
const stats = ctx.memory.getStats();
console.log(stats);
```
### Default Collection Semantics
- `trackToolCalls`, `trackPreferences`, `trackProjectContext`, and `trackSessionHistory` default to `false` and control their respective automatic collection paths.
- With the default configuration, startup keeps an empty memory in RAM, does not create `.dsh-memory.json`, and does not record `metadata.totalSessions`.
- `setPreference()`, `recordTopic()`, `recordTask()`, `addProject()`, `storage.set()`, and `importData()` are explicit operations and persist data even when automatic collection is disabled.
- Enabling any automatic collection toggle makes startup load or create the storage file and record one session in the metadata.
## โ๏ธ Configuration Options
```javascript
{
// Storage file path (relative to workspace)
storagePath: '.dsh-memory.json',
// Maximum number of history items
maxHistoryItems: 100,
// Auto-save interval (milliseconds)
autoSaveInterval: 5000,
// Automatic collection toggles (disabled by default; explicitly set to true to opt in)
trackToolCalls: false, // Track tool calls
trackPreferences: false, // Track user preferences
trackProjectContext: false, // Track project context
trackSessionHistory: false, // Track session history
// Privacy settings
encryptSensitiveData: false, // Legacy compatibility field; redaction is always enabled
allowClearMemory: true, // Allow clearing memory
// Smart features
enableRecommendations: true, // Enable recommendations
patternRecognitionThreshold: 3 // Pattern recognition threshold
}
```
## ๐จ Web Viewer
The plugin provides a beautiful web interface to visualize memory data:
```bash
# Double-click to run
open-viewer.cmd
# Or open in browser
viewer.html
# For the extended dashboard layout
premium-viewer.html
```
Viewer features:
- ๐ Data overview cards
- ๐ ๏ธ Tool usage statistics charts
- ๐ Project management list
- ๐ฌ Session history timeline
- ๐ฏ Smart recommendation display
## ๐ Data Structure
Memory data is stored in JSON format:
```json
{
"version": "1.0.0",
"userPreferences": {
"defaultModel": "qwen3.7-plus",
"language": "en-US",
"preferredAgents": ["coding-assistant", "reviewer"]
},
"inputHabits": {
"preferredTools": ["read", "write", "glob"],
"commonCommands": [
{"command": "npm run dev", "count": 45}
]
},
"projectContext": {
"activeProjects": [
{
"path": "/projects/my-app",
"name": "my-app",
"tags": ["react", "typescript"],
"lastAccessed": "2026-08-20T10:30:00Z"
}
]
},
"sessionHistory": {
"recentTopics": [
{"content": "plugin development", "timestamp": "2026-08-20T10:00:00Z"}
],
"toolUsageStats": {
"read": 156,
"write": 89,
"edit": 67
}
},
"metadata": {
"createdAt": "2026-08-20T00:00:00Z",
"totalSessions": 25,
"lastSessionDate": "2026-08-20T10:30:00Z"
}
}
```
## ๐ Privacy & Security
- โ
**Fully Transparent** - All data stored in local JSON files
- โ
**User Control** - Can disable any tracking feature
- โ
**Data Ownership** - Data belongs entirely to the user, can be exported or deleted anytime
- โ
**No Cloud Sync** - All data stored locally only
- โ
**Clearable** - Use `ctx.memory.clearMemory()` to clear plugin memory; the viewer button only clears browser cache
## ๐ ๏ธ Project Structure
```
dsh-memory-plugin/
โโโ index.js # Main entry point
โโโ config.js # Configuration validation module
โโโ storage.js # Data storage engine
โโโ memory-manager.js # Core memory management
โโโ package.json # NPM package configuration
โโโ viewer.html # Default web viewer
โโโ premium-viewer.html # Professional web viewer
โโโ demo-viewer.html # Demo viewer
โโโ open-viewer.cmd # One-click launch script
โโโ quick-start.js # Quick sample data generator
โโโ test/ # Test files
โ โโโ config.test.js
โ โโโ storage.test.js
โ โโโ memory-manager.test.js
โโโ README.md # Chinese documentation
โโโ README.en.md # English documentation
โโโ LICENSE # MIT License
โโโ CONTRIBUTING.md # Contribution guidelines
```
## ๐งช Testing
```bash
# Run tests
npm test
# Run the real DSH clean-profile E2E (skips safely when dsh is unavailable)
npm run test:dsh-e2e
# Run quick demo
node quick-start.js
# Open web viewer
./open-viewer.cmd
```
## ๐ก Use Cases
### Use Case 1: Personalized Assistant
```javascript
// Auto-configure based on user preferences
const model = ctx.memory.getPreference('defaultModel');
const agents = ctx.memory.getPreference('preferredAgents');
// Automatically use user's preferred configuration
```
### Use Case 2: Smart Recommendations
```javascript
// Get recommendations while coding
const recs = ctx.memory.getRecommendations('coding');
// Returns: recommended Agents, models, projects, etc.
```
### Use Case 3: Project Switching
```javascript
// Automatically identify and record projects
await ctx.memory.addProject({
path: process.cwd(),
name: 'current-project',
tags: ['typescript', 'api']
});
```
## ๐ค Contributing
Contributions, issues, and suggestions are welcome!
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) - Powerful AI development assistant framework
---
**Made with โค๏ธ by ly028716**
[โญ Star this repo](https://github.com/ly028716/dsh-memory-plugin) | [๐ Report Bug](https://github.com/ly028716/dsh-memory-plugin/issues) | [๐ก Request Feature](https://github.com/ly028716/dsh-memory-plugin/issues)