Variet/guitar_score
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wip: [01-stabilize] paused at task 1/1 - OCR Hallucination Immune logic via Semantic delta window and fret-isolation

Browse Source
This commit is contained in:
authentik Default Admin
2026-03-29 22:08:40 +09:00
parent aca7bf592a
commit 2507de45d3
4289 changed files with 732689 additions and 28672 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
.agent/services/claude-mem/.claude-plugin/CLAUDE.md Normal file
View File

@@ -0,0 +1,136 @@
<claude-mem-context>
# Recent Activity
### Oct 25, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #2374 | 2:55 PM | ✅ | Marketplace metadata version synchronized to 4.2.11 | ~157 |
### Oct 27, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #2757 | 1:23 AM | 🟣 | Released v4.3.3 with Configurable Session Display and First-Time Setup UX | ~391 |
### Nov 4, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #3706 | 9:47 PM | ✅ | Marketplace Plugin Version Synchronized to 5.0.2 | ~162 |
| #3655 | 3:43 PM | ✅ | Version bumped to 5.0.1 across project | ~354 |
### Nov 5, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #4068 | 10:58 PM | ✅ | Committed v5.1.0 release with comprehensive release notes | ~486 |
| #4066 | 10:57 PM | ✅ | Updated marketplace.json version to 5.1.0 | ~192 |
| #3739 | 2:24 PM | ✅ | Updated version to 5.0.3 across project manifests | ~322 |
### Nov 6, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #4099 | 1:13 PM | 🟣 | Theme Toggle for Light/Dark Mode | ~253 |
| #4096 | " | ✅ | Marketplace Metadata Version Sync | ~179 |
| #4092 | 1:12 PM | 🔵 | Marketplace Configuration for Claude-Mem Plugin | ~194 |
| #4078 | 12:50 PM | 🔴 | Fixed PM2 ENOENT error on Windows systems | ~286 |
| #4075 | 12:49 PM | ✅ | Marketplace plugin version synchronized to 5.1.1 | ~189 |
### Nov 7, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #4612 | 6:33 PM | ✅ | Version Bumped to 5.2.0 Across All Package Metadata | ~359 |
| #4598 | 6:31 PM | ✅ | PR #69 Merged: cleanup/worker Branch Integration | ~469 |
| #4298 | 11:54 AM | 🔴 | Fixed PostToolUse Hook Schema Compliance | ~310 |
| #4295 | 11:53 AM | ✅ | Synchronized Plugin Marketplace Version to 5.1.4 | ~188 |
### Nov 8, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #5150 | 7:37 PM | 🟣 | Troubleshooting Skill Added to Claude-Mem Plugin | ~427 |
| #5133 | 7:29 PM | ✅ | Version 5.2.3 Released with Build Process | ~487 |
### Nov 9, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #5941 | 7:14 PM | ✅ | Marketplace Version Updated to 5.4.0 | ~157 |
### Nov 10, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #6341 | 1:49 PM | ✅ | Version Bumped to 5.4.1 | ~239 |
### Nov 11, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #6602 | 1:51 PM | ✅ | Version 5.4.5 Released to GitHub | ~279 |
| #6601 | " | ✅ | Version Patch Bump 5.4.4 to 5.4.5 | ~233 |
### Nov 14, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #8212 | 3:06 PM | 🔵 | Version Consistency Verification Across Multiple Configuration Files | ~238 |
### Nov 25, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #14882 | 1:32 PM | 🔵 | Marketplace Configuration Defines Plugin Version and Source Directory | ~366 |
### Nov 30, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #18064 | 10:52 PM | ✅ | Bumped version to 6.3.7 in marketplace.json | ~179 |
| #18060 | 10:51 PM | 🔵 | Read marketplace.json plugin manifest | ~190 |
### Dec 1, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #18428 | 3:33 PM | 🔵 | Version Conflict in Marketplace Configuration | ~191 |
### Dec 4, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #20049 | 3:23 PM | ✅ | Updated marketplace.json version to 6.5.2 | ~203 |
### Dec 9, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #22559 | 1:08 AM | ✅ | Version 7.0.3 committed to repository | ~261 |
| #22551 | 1:07 AM | ✅ | Marketplace metadata updated to version 7.0.3 | ~179 |
### Dec 10, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #23440 | 2:25 PM | ✅ | Marketplace Configuration Updated to 7.0.8 | ~188 |
### Dec 14, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #26799 | 11:39 PM | ✅ | Marketplace Manifest Version Updated to 7.2.3 | ~248 |
| #26796 | " | ✅ | Version Bumped to 7.2.3 in marketplace.json | ~259 |
| #26792 | 11:38 PM | 🔵 | Current Version Confirmed as 7.2.2 Across All Configuration Files | ~291 |
### Dec 16, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #28306 | 10:08 PM | 🔵 | Marketplace Configuration Also Shows Version 7.3.3 | ~220 |
| #27555 | 4:48 PM | ✅ | Version bump committed to main branch | ~242 |
| #27553 | " | ✅ | Version consistency verified across all configuration files | ~195 |
| #27551 | 4:47 PM | ✅ | Marketplace.json version updated to 7.3.1 | ~207 |
</claude-mem-context>

18
.agent/services/claude-mem/.claude-plugin/marketplace.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "thedotmack",
"owner": {
"name": "Alex Newman"
},
"metadata": {
"description": "Plugins by Alex Newman (thedotmack)",
"homepage": "https://github.com/thedotmack/claude-mem"
},
"plugins": [
{
"name": "claude-mem",
"version": "10.6.2",
"source": "./plugin",
"description": "Persistent memory system for Claude Code - context compression across sessions"
}
]
}

17
.agent/services/claude-mem/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "claude-mem",
"version": "10.4.1",
"description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions",
"author": {
"name": "Alex Newman"
},
"repository": "https://github.com/thedotmack/claude-mem",
"license": "AGPL-3.0",
"keywords": [
"memory",
"context",
"persistence",
"hooks",
"mcp"
]
}

1
.agent/services/claude-mem/.github/FUNDING.yml vendored Normal file
View File

@@ -0,0 +1 @@
github: thedotmack

74
.agent/services/claude-mem/.github/ISSUE_TEMPLATE/bug_report.md vendored Normal file
View File

@@ -0,0 +1,74 @@
---
name: Bug report
about: Use the automated bug report tool for best results
title: ''
labels: 'bug, needs-triage'
assignees: ''
---
## Before submitting
- [ ] I searched [existing issues](https://github.com/thedotmack/claude-mem/issues) and confirmed this is not a duplicate
---
## ⚡ Quick Bug Report (Recommended)
**Use the automated bug report generator** for comprehensive diagnostics:
```bash
# Navigate to the plugin directory
cd ~/.claude/plugins/marketplaces/thedotmack
# Run the bug report tool
npm run bug-report
```
**Plugin Paths:**
- **macOS/Linux**: `~/.claude/plugins/marketplaces/thedotmack`
- **Windows**: `%USERPROFILE%\.claude\plugins\marketplaces\thedotmack`
**Features:**
- 🌎 Auto-translates any language to English
- 📊 Collects all diagnostics automatically
- 🤖 AI-formatted professional issue
- 🔒 Privacy-safe (paths sanitized, `--no-logs` option)
- 🌐 Auto-opens GitHub with pre-filled issue
---
## 📝 Manual Bug Report
If you prefer to file manually or can't access the plugin directory:
### Bug Description
A clear description of what the bug is.
### Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error
### Expected Behavior
What you expected to happen.
### Environment
- **Claude-mem version**:
- **Claude Code version**:
- **OS**:
- **Platform**:
### Logs
Worker logs are located at:
- **Path**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
- **Example**: `~/.claude-mem/logs/worker-2025-12-14.log`
Please paste relevant log entries (last 50 lines or error messages):
```
[Paste logs here]
```
### Additional Context
Any other context about the problem.

26
.agent/services/claude-mem/.github/ISSUE_TEMPLATE/feature_request.md vendored Normal file
View File

@@ -0,0 +1,26 @@
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: feature-request
assignees: ''
---
## Before submitting
- [ ] I searched [existing issues](https://github.com/thedotmack/claude-mem/issues) and confirmed this is not a duplicate
---
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context or screenshots about the feature request here.

57
.agent/services/claude-mem/.github/workflows/claude-code-review.yml vendored Normal file
View File

@@ -0,0 +1,57 @@
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
# Optional: Only run on specific file changes
# paths:
# - "src/**/*.ts"
# - "src/**/*.tsx"
# - "src/**/*.js"
# - "src/**/*.jsx"
jobs:
claude-review:
# Optional: Filter by PR author
# if: |
# github.event.pull_request.user.login == 'external-contributor' ||
# github.event.pull_request.user.login == 'new-developer' ||
# github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 1
- name: Run Claude Code Review
id: claude-review
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
prompt: |
REPO: ${{ github.repository }}
PR NUMBER: ${{ github.event.pull_request.number }}
Please review this pull request and provide feedback on:
- Code quality and best practices
- Potential bugs or issues
- Performance considerations
- Security concerns
- Test coverage
Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
# or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

50
.agent/services/claude-mem/.github/workflows/claude.yml vendored Normal file
View File

@@ -0,0 +1,50 @@
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]
pull_request_review:
types: [submitted]
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
actions: read # Required for Claude to read CI results on PRs
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 1
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
# This is an optional setting that allows Claude to read CI results on PRs
additional_permissions: |
actions: read
# Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
# prompt: 'Update the pull request description to include a summary of changes.'
# Optional: Add claude_args to customize behavior and configuration
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
# or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
# claude_args: '--allowed-tools Bash(gh pr:*)'

131
.agent/services/claude-mem/.github/workflows/convert-feature-requests.yml vendored Normal file
View File

@@ -0,0 +1,131 @@
name: Convert Feature Requests to Discussions
on:
issues:
types: [labeled]
workflow_dispatch:
inputs:
issue_number:
description: 'Issue number to convert to discussion'
required: true
type: number
jobs:
convert:
runs-on: ubuntu-latest
# Only run on labeled event if the label is 'feature-request', or always run on workflow_dispatch
if: |
(github.event_name == 'issues' && github.event.label.name == 'feature-request') ||
github.event_name == 'workflow_dispatch'
permissions:
issues: write
discussions: write
contents: read
steps:
- name: Get issue details and create discussion
id: discussion
uses: actions/github-script@v8
with:
script: |
// Get issue details
let issue;
if (context.eventName === 'workflow_dispatch') {
const { data } = await github.rest.issues.get({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.inputs.issue_number
});
issue = data;
} else {
issue = context.payload.issue;
}
console.log(`Processing issue #${issue.number}: ${issue.title}`);
// Format the discussion body with a reference to the original issue
const discussionBody = `> Originally posted as issue #${issue.number} by @${issue.user.login}\n> ${issue.html_url}\n\n${issue.body || 'No description provided.'}`;
const mutation = `
mutation($repositoryId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
createDiscussion(input: {
repositoryId: $repositoryId
categoryId: $categoryId
title: $title
body: $body
}) {
discussion {
url
number
}
}
}
`;
const variables = {
repositoryId: 'R_kgDOPng1Jw',
categoryId: 'DIC_kwDOPng1J84Cw86z',
title: issue.title,
body: discussionBody
};
try {
const result = await github.graphql(mutation, variables);
const discussionUrl = result.createDiscussion.discussion.url;
const discussionNumber = result.createDiscussion.discussion.number;
core.setOutput('url', discussionUrl);
core.setOutput('number', discussionNumber);
core.setOutput('issue_number', issue.number);
console.log(`Created discussion #${discussionNumber}: ${discussionUrl}`);
return { discussionUrl, discussionNumber, issueNumber: issue.number };
} catch (error) {
core.setFailed(`Failed to create discussion: ${error.message}`);
throw error;
}
- name: Comment on issue
uses: actions/github-script@v8
with:
script: |
const issueNumber = ${{ steps.discussion.outputs.issue_number }};
const discussionUrl = '${{ steps.discussion.outputs.url }}';
const comment = `This feature request has been moved to [Discussions](${discussionUrl}) to keep bug reports separate from feature ideas.\n\nPlease continue the conversation there - we'd love to hear your thoughts!`;
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: issueNumber,
body: comment
});
console.log(`Added comment to issue #${issueNumber}`);
- name: Close and lock issue
uses: actions/github-script@v8
with:
script: |
const issueNumber = ${{ steps.discussion.outputs.issue_number }};
// Close the issue
await github.rest.issues.update({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: issueNumber,
state: 'closed'
});
console.log(`Closed issue #${issueNumber}`);
// Lock the issue
await github.rest.issues.lock({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: issueNumber,
lock_reason: 'resolved'
});
console.log(`Locked issue #${issueNumber}`);

29
.agent/services/claude-mem/.github/workflows/deploy-install-scripts.yml vendored Normal file
View File

@@ -0,0 +1,29 @@
name: Deploy Install Scripts
on:
push:
branches: [main]
paths:
- 'openclaw/install.sh'
- 'install/**'
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Copy install scripts to deploy directory
run: |
mkdir -p install/public
cp openclaw/install.sh install/public/openclaw.sh
- name: Deploy to Vercel
uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
vercel-args: '--prod'
working-directory: ./install

21
.agent/services/claude-mem/.github/workflows/npm-publish.yml vendored Normal file
View File

@@ -0,0 +1,21 @@
name: Publish to npm
on:
push:
tags:
- 'v*'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- run: npm install --ignore-scripts
- run: npm run build
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

34
.agent/services/claude-mem/.github/workflows/summary.yml vendored Normal file
View File

@@ -0,0 +1,34 @@
name: Summarize new issues
on:
issues:
types: [opened]
jobs:
summary:
runs-on: ubuntu-latest
permissions:
issues: write
models: read
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Run AI inference
id: inference
uses: actions/ai-inference@v2
with:
prompt: |
Summarize the following GitHub issue in one paragraph:
Title: ${{ github.event.issue.title }}
Body: ${{ github.event.issue.body }}
- name: Comment with AI summary
run: |
gh issue comment $ISSUE_NUMBER --body '${{ steps.inference.outputs.response }}'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ISSUE_NUMBER: ${{ github.event.issue.number }}
RESPONSE: ${{ steps.inference.outputs.response }}

38
.agent/services/claude-mem/.gitignore vendored Normal file
View File

@@ -0,0 +1,38 @@
datasets/
node_modules/
dist/
!installer/dist/
**/_tree-sitter/
*.log
.DS_Store
.env
.env.local
*.tmp
*.temp
.install-version
.claude/settings.local.json
.claude/agents/
.claude/skills/
.claude/plans/
.claude/worktrees/
plugin/data/
plugin/data.backup/
package-lock.json
bun.lock
private/
Auto Run Docs/
# Generated UI files (built from viewer-template.html)
src/ui/viewer.html
# Local MCP server config (for development only)
.mcp.json
.cursor/
# Ignore WebStorm project files (for dinosaur IDE users)
.idea/
.claude-octopus/
.claude/session-intent.md
.claude/session-plan.md
.octo/

3
.agent/services/claude-mem/.markdownlint.json Normal file
View File

@@ -0,0 +1,3 @@
{
"MD013": false
}

736
.agent/services/claude-mem/.plan/npx-distribution.md Normal file
View File

@@ -0,0 +1,736 @@
# Plan: NPX Distribution + Universal IDE/CLI Coverage for claude-mem
## Problem
1. **Installation is slow and fragile**: Current install clones the full git repo, runs `npm install`, and builds from source. The npm package already ships pre-built artifacts.
2. **IDE coverage is limited**: claude-mem only supports Claude Code (plugin) and Cursor (hooks installer). The AI coding tools landscape has exploded — Gemini CLI (95k stars), OpenCode (110k stars), Windsurf (~1M users), Codex CLI, Antigravity, Goose, Crush, Copilot CLI, and more all support extensibility.
## Key Insights
- **npm package already has everything**: `plugin/` directory ships pre-built. No git clone or build needed.
- **Transcript watcher already exists**: `src/services/transcripts/` has a fully built schema-based JSONL tailer. It just needs schemas for more tools.
- **3 integration tiers exist**: (1) Hook/plugin-based (Claude Code, Gemini CLI, OpenCode, Windsurf, Codex CLI, OpenClaw), (2) MCP-based (Cursor, Copilot CLI, Antigravity, Goose, Crush, Roo Code), (3) Transcript-based (anything with structured log files).
- **OpenClaw plugin already built**: Full plugin at `openclaw/src/index.ts` (1000+ lines). Needs to be wired into the npx installer.
- **Gemini CLI is architecturally near-identical to Claude Code**: 11 lifecycle hooks, JSON via stdin/stdout, exit code 0/2 convention, `GEMINI.md` context files, `~/.gemini/settings.json`. This is the easiest high-value integration.
- **OpenCode has the richest plugin system**: 20+ hook events across 12 categories, JS/TS plugin modules, custom tool creation, MCP support. 110k stars — largest open-source AI CLI.
- **`npx skills` by Vercel supports 41 agents** — proving the multi-IDE installer UX works. Their agent detection pattern (check if config dir exists) is the right model.
- **All IDEs share a single worker on port 37777**: One worker serves all integrations. Session source (which IDE) is tracked via the `source` field in hook payloads. No per-IDE worker instances.
- **This npx CLI fully replaces the old `claude-mem-installer`**: Not a supplement — the complete replacement.
## Solution
`npx claude-mem` becomes a unified CLI: install, configure any IDE, manage the worker, search memory.
```
npx claude-mem # Interactive install + IDE selection
npx claude-mem install # Same as above
npx claude-mem install --ide windsurf # Direct IDE setup
npx claude-mem start / stop / status # Worker management
npx claude-mem search <query> # Search memory from terminal
npx claude-mem transcript watch # Start transcript watcher
```
## Platform Support
**Windows, macOS, and Linux are all first-class targets.** Platform-specific considerations:
- **Config paths**: Use `os.homedir()` and `path.join()` everywhere — never hardcode `/` or `~`
- **Shebangs**: `#!/usr/bin/env node` for the CLI entry point (cross-platform via Node)
- **Bun detection**: Check `PATH`, common install locations per platform (`%USERPROFILE%\.bun\bin\bun.exe` on Windows, `~/.bun/bin/bun` on Unix)
- **File permissions**: `fs.chmod` is a no-op on Windows; don't gate on it
- **Process management**: Worker start/stop uses signals on Unix, taskkill on Windows — match existing `worker-service.ts` patterns
- **VS Code paths**: `~/Library/Application Support/Code/` (macOS), `~/.config/Code/` (Linux), `%APPDATA%/Code/` (Windows)
- **Shell config**: `.bashrc`/`.zshrc` on Unix, PowerShell profile on Windows (for PATH modifications if needed)
---
## Phase 0: Research Findings
### IDE Integration Tiers
**Tier 1 — Native Hook/Plugin Systems** (highest fidelity, real-time capture):
| Tool | Hooks | Config Location | Context Injection | Stars/Users |
|------|-------|----------------|-------------------|-------------|
| Claude Code | 5 lifecycle hooks | `~/.claude/settings.json` | CLAUDE.md, plugins | ~25% market |
| Gemini CLI | 11 lifecycle hooks | `~/.gemini/settings.json` | GEMINI.md | ~95k stars |
| OpenCode | 20+ event hooks + plugin SDK | `~/.config/opencode/opencode.json` | AGENTS.md + rules dirs | ~110k stars |
| Windsurf | 11 Cascade hooks | `.windsurf/hooks.json` | `.windsurf/rules/*.md` | ~1M users |
| Codex CLI | `notify` hook | `~/.codex/config.toml` | `.codex/AGENTS.md`, MCP | Growing (OpenAI) |
| OpenClaw | 8 event hooks + plugin SDK | `~/.openclaw/openclaw.json` | MEMORY.md sync | ~196k stars |
**Tier 2 — MCP Integration** (tool-based, search + context injection):
| Tool | MCP Support | Config Location | Context Injection |
|------|------------|----------------|-------------------|
| Cursor | First-class | `.cursor/mcp.json` | `.cursor/rules/*.mdc` |
| Copilot CLI | First-class (default MCP) | `~/.copilot/config` | `.github/copilot-instructions.md` |
| Antigravity | First-class + MCP Store | `~/.gemini/antigravity/mcp_config.json` | `.agent/rules/`, GEMINI.md |
| Goose | Native MCP (co-developed protocol) | `~/.config/goose/config.yaml` | MCP context |
| Crush | MCP + Skills | JSON config (charm.land schema) | Skills system |
| Roo Code | First-class | `.roo/` | `.roo/rules/*.md`, `AGENTS.md` |
| Warp | MCP + Warp Drive | `WARP.md` + Warp Drive UI | `WARP.md` |
**Tier 3 — Transcript File Watching** (passive, file-based):
| Tool | Transcript Location | Format |
|------|-------------------|--------|
| Claude Code | `~/.claude/projects/<proj>/<session>.jsonl` | JSONL |
| Codex CLI | `~/.codex/sessions/**/*.jsonl` | JSONL |
| Gemini CLI | `~/.gemini/tmp/<hash>/chats/` | JSON |
| OpenCode | `.opencode/` (SQLite) | SQLite — needs export |
### What claude-mem Already Has
| Component | Status | Location |
|-----------|--------|----------|
| Claude Code plugin | Complete | `plugin/hooks/hooks.json` |
| Cursor hooks installer | Complete | `src/services/integrations/CursorHooksInstaller.ts` |
| Platform adapters | Claude Code + Cursor + raw | `src/cli/adapters/` |
| Transcript watcher | Complete (schema-based JSONL) | `src/services/transcripts/` |
| Codex transcript schema | Sample exists | `src/services/transcripts/config.ts` |
| OpenClaw plugin | Complete (1000+ lines) | `openclaw/src/index.ts` |
| MCP server | Complete | `plugin/scripts/mcp-server.cjs` |
| Gemini CLI support | Not started | — |
| OpenCode support | Not started | — |
| Windsurf support | Not started | — |
### Patterns to Copy
- **Agent detection from `npx skills`** (`vercel-labs/skills/src/agents.ts`): Check if config directory exists
- **Existing installer logic** (`installer/src/steps/install.ts:29-83`): registerMarketplace, registerPlugin, enablePluginInClaudeSettings — **extract shared logic** from existing installer into reusable modules (DRY with the new CLI)
- **Bun resolution** (`plugin/scripts/bun-runner.js`): PATH lookup + common locations per platform
- **CursorHooksInstaller** (`src/services/integrations/CursorHooksInstaller.ts`): Reference implementation for IDE hooks installation
---
## Phase 1: NPX CLI Entry Point
### What to implement
1. **Add `bin` field to `package.json`**:
```json
"bin": {
"claude-mem": "./dist/cli/index.js"
}
```
2. **Create `src/npx-cli/index.ts`** — a Node.js CLI router (NOT Bun) with command categories:
**Install commands** (pure Node.js, no Bun required):
- `npx claude-mem` or `npx claude-mem install` → interactive install (IDE multi-select)
- `npx claude-mem install --ide <name>` → direct IDE setup (only for implemented IDEs; unimplemented ones error with "Support for <name> coming soon")
- `npx claude-mem update` → update to latest version
- `npx claude-mem uninstall` → remove plugin and IDE configs
- `npx claude-mem version` → print version
**Runtime commands** (delegate to Bun via installed plugin):
- `npx claude-mem start` → spawns `bun worker-service.cjs start`
- `npx claude-mem stop` → spawns `bun worker-service.cjs stop`
- `npx claude-mem restart` → spawns `bun worker-service.cjs restart`
- `npx claude-mem status` → spawns `bun worker-service.cjs status`
- `npx claude-mem search <query>` → hits `GET http://localhost:37777/api/search?q=<query>`
- `npx claude-mem transcript watch` → starts transcript watcher
**Runtime commands must check for installation first**: If plugin directory doesn't exist at `~/.claude/plugins/marketplaces/thedotmack/`, print "claude-mem is not installed. Run: npx claude-mem install" and exit.
3. **The install flow** (fully replaces git clone + build):
- Detect the npm package's own location (`import.meta.url` or `__dirname`)
- Copy `plugin/` from the npm package to `~/.claude/plugins/marketplaces/thedotmack/`
- Copy `plugin/` to `~/.claude/plugins/cache/thedotmack/claude-mem/<version>/`
- Register marketplace in `~/.claude/plugins/known_marketplaces.json`
- Register plugin in `~/.claude/plugins/installed_plugins.json`
- Enable in `~/.claude/settings.json`
- Run `npm install` in the marketplace dir (for `@chroma-core/default-embed` — native ONNX binaries, can't be bundled)
- Trigger smart-install.js for Bun/uv setup
- Run IDE-specific setup for each selected IDE
4. **Interactive IDE selection** (auto-detect + prompt):
- Auto-detect installed IDEs by checking config directories
- Present multi-select with detected IDEs pre-selected
- Detection map:
- Claude Code: `~/.claude/` exists
- Gemini CLI: `~/.gemini/` exists
- OpenCode: `~/.config/opencode/` exists OR `opencode` in PATH
- OpenClaw: `~/.openclaw/` exists
- Windsurf: `~/.codeium/windsurf/` exists
- Codex CLI: `~/.codex/` exists
- Cursor: `~/.cursor/` exists
- Copilot CLI: `copilot` in PATH (it's a CLI tool, not a config dir)
- Antigravity: `~/.gemini/antigravity/` exists
- Goose: `~/.config/goose/` exists OR `goose` in PATH
- Crush: `crush` in PATH
- Roo Code: check for VS Code extension directory containing `roo-code`
- Warp: `~/.warp/` exists OR `warp` in PATH
5. **The runtime command routing**:
- Locate the installed plugin directory
- Find Bun binary (same logic as `bun-runner.js`, platform-aware)
- Spawn `bun worker-service.cjs <command>` and pipe stdio through
- For `search`: HTTP request to running worker
### Patterns to follow
- `installer/src/steps/install.ts:29-83` for marketplace registration — **extract to shared module**
- `plugin/scripts/bun-runner.js` for Bun resolution
- `vercel-labs/skills/src/agents.ts` for IDE auto-detection pattern
### Verification
- `npx claude-mem install` copies plugin to correct directories on macOS, Linux, and Windows
- Auto-detection finds installed IDEs
- `npx claude-mem start/stop/status` work after install
- `npx claude-mem search "test"` returns results
- `npx claude-mem start` before install prints helpful error message
- `npx claude-mem update` and `npx claude-mem uninstall` work correctly
- `npx claude-mem version` prints version
### Anti-patterns
- Do NOT require Bun for install commands — pure Node.js
- Do NOT clone the git repo
- Do NOT build from source at install time
- Do NOT depend on `bun:sqlite` in the CLI entry point
---
## Phase 2: Build Pipeline Integration
### What to implement
1. **Add CLI build step to `scripts/build-hooks.js`**:
- Compile `src/npx-cli/index.ts` → `dist/cli/index.js`
- Bundle `@clack/prompts` and `picocolors` into the output (self-contained)
- Shebang: `#!/usr/bin/env node`
- Set executable permissions (no-op on Windows, that's fine)
2. **Move `@clack/prompts` and `picocolors`** to main package.json as dev dependencies (bundled by esbuild into dist/cli/index.js)
3. **Verify `package.json` `files` field**: Currently `["dist", "plugin"]`. `dist/cli/index.js` is already included since it's under `dist/`. No change needed.
4. **Update `prepublishOnly`** to ensure CLI is built before npm publish (already covered — `npm run build` calls `build-hooks.js`)
5. **Pre-build OpenClaw plugin**: Add an esbuild step that compiles `openclaw/src/index.ts` → `openclaw/dist/index.js` so it ships ready-to-use. No `tsc` at install time.
6. **Add `openclaw/dist/` to `package.json` `files` field** (or add `openclaw` if the whole directory should ship)
### Verification
- `npm run build` produces `dist/cli/index.js` with correct shebang
- `npm run build` produces `openclaw/dist/index.js` pre-built
- `npm pack` includes both `dist/cli/index.js` and `openclaw/dist/`
- `node dist/cli/index.js --help` works without Bun
- Package size is reasonable (check with `npm pack --dry-run`)
---
## Phase 3: Gemini CLI Integration (Tier 1 — Hook-Based)
**Why first among new IDEs**: Near-identical architecture to Claude Code. 11 lifecycle hooks with JSON stdin/stdout, same exit code conventions (0=success, 2=block), `GEMINI.md` context files. 95k GitHub stars. Lowest effort, highest confidence.
### Gemini CLI Hook Events
| Event | Map to claude-mem | Use |
|-------|-------------------|-----|
| `SessionStart` | `session-init` | Start tracking session |
| `BeforeAgent` | `user-prompt` | Capture user prompt |
| `AfterAgent` | `observation` | Capture full agent response |
| `BeforeTool` | — | Skip (pre-execution, no result yet) |
| `AfterTool` | `observation` | Capture tool name + input + response |
| `BeforeModel` | — | Skip (too low-level, LLM request details) |
| `AfterModel` | — | Skip (raw LLM response, redundant with AfterAgent) |
| `BeforeToolSelection` | — | Skip (internal planning step) |
| `PreCompress` | `summary` | Trigger summary before context compression |
| `Notification` | — | Skip (system alerts, not session data) |
| `SessionEnd` | `session-end` | Finalize session |
**Mapped**: 5 of 11 events. **Skipped**: 6 events that are either too low-level (BeforeModel/AfterModel), pre-execution (BeforeTool, BeforeToolSelection), or system-level (Notification).
### Verified Stdin Payload Schemas (from `packages/core/src/hooks/types.ts`)
**Base input (all hooks receive):**
```typescript
{ session_id: string, transcript_path: string, cwd: string, hook_event_name: string, timestamp: string }
```
**Event-specific fields:**
| Event | Additional Fields |
|-------|-------------------|
| `SessionStart` | `source: "startup" \| "resume" \| "clear"` |
| `SessionEnd` | `reason: "exit" \| "clear" \| "logout" \| "prompt_input_exit" \| "other"` |
| `BeforeAgent` | `prompt: string` |
| `AfterAgent` | `prompt: string, prompt_response: string, stop_hook_active: boolean` |
| `BeforeTool` | `tool_name: string, tool_input: Record<string, unknown>, mcp_context?: McpToolContext, original_request_name?: string` |
| `AfterTool` | `tool_name: string, tool_input: Record<string, unknown>, tool_response: Record<string, unknown>, mcp_context?: McpToolContext` |
| `PreCompress` | `trigger: "auto" \| "manual"` |
| `Notification` | `notification_type: "ToolPermission", message: string, details: Record<string, unknown>` |
**Output (all hooks can return):**
```typescript
{ continue?: boolean, stopReason?: string, suppressOutput?: boolean, systemMessage?: string, decision?: "allow" | "deny" | "block" | "approve" | "ask", reason?: string, hookSpecificOutput?: Record<string, unknown> }
```
**Advisory (non-blocking) hooks:** SessionStart, SessionEnd, PreCompress, Notification — `continue` and `decision` fields are ignored.
**Environment variables provided:** `GEMINI_PROJECT_DIR`, `GEMINI_SESSION_ID`, `GEMINI_CWD`, `CLAUDE_PROJECT_DIR` (compat alias)
### What to implement
1. **Create Gemini CLI platform adapter** at `src/cli/adapters/gemini-cli.ts`:
- Normalize Gemini CLI's hook JSON to `NormalizedHookInput`
- Base fields always present: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `timestamp`
- Map per event:
- `SessionStart`: `source` → session init metadata
- `BeforeAgent`: `prompt` → user prompt text
- `AfterAgent`: `prompt` + `prompt_response` → full conversation turn
- `AfterTool`: `tool_name` + `tool_input` + `tool_response` → observation
- `PreCompress`: `trigger` → summary trigger
- `SessionEnd`: `reason` → session finalization
2. **Create Gemini CLI hooks installer** at `src/services/integrations/GeminiCliHooksInstaller.ts`:
- Write hooks to `~/.gemini/settings.json` under the `hooks` key
- Must **merge** with existing settings (read → parse → deep merge → write)
- Hook config format (verified against official docs):
```json
{
"hooks": {
"AfterTool": [{
"matcher": "*",
"hooks": [{ "name": "claude-mem", "type": "command", "command": "<path-to-hook-script>", "timeout": 5000 }]
}]
}
}
```
- Note: `matcher` uses regex for tool events, exact string for lifecycle events. `"*"` or `""` matches all.
- Hook groups support `sequential: boolean` (default false = parallel execution)
- Security: Project-level hooks are fingerprinted — if name/command changes, user is warned
- Context injection via `~/.gemini/GEMINI.md` (append claude-mem section with `<claude-mem-context>` tags, same pattern as CLAUDE.md)
- Settings hierarchy: project `.gemini/settings.json` > user `~/.gemini/settings.json` > system `/etc/gemini-cli/settings.json`
3. **Register `gemini-cli` in `getPlatformAdapter()`** at `src/cli/adapters/index.ts`
4. **Add Gemini CLI to installer IDE selection**
### Verification
- `npx claude-mem install --ide gemini-cli` merges hooks into `~/.gemini/settings.json`
- Gemini CLI sessions are captured by the worker
- `AfterTool` events produce observations with correct `tool_name`, `tool_input`, `tool_response`
- `GEMINI.md` gets claude-mem context section
- Existing Gemini CLI settings are preserved (merge, not overwrite)
- Verify `session_id` from base input is used for session tracking
### Anti-patterns
- Do NOT overwrite `~/.gemini/settings.json` — must deep merge
- Do NOT map all 11 events — the 6 skipped events would produce noise, not signal
- Do NOT use `type: "runtime"` — that's for internal extensions only; use `type: "command"`
- Advisory hooks (SessionStart, SessionEnd, PreCompress, Notification) cannot block — don't set `decision` or `continue` fields on them
---
## Phase 4: OpenCode Integration (Tier 1 — Plugin-Based)
**Why next**: 110k stars, richest plugin ecosystem. OpenCode plugins are JS/TS modules auto-loaded from plugin directories. OpenCode also has a Claude Code compatibility fallback (reads `~/.claude/CLAUDE.md` if no global `AGENTS.md` exists, controllable via `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1`).
### Verified Plugin API (from `packages/plugin/src/index.ts`)
**Plugin signature:**
```typescript
import { type Plugin, tool } from "@opencode-ai/plugin"
export const ClaudeMemPlugin: Plugin = async (ctx) => {
// ctx: { client, project, directory, worktree, serverUrl, $ }
return { /* hooks object */ }
}
```
**PluginInput type (6 properties, not 4):**
```typescript
type PluginInput = {
client: ReturnType<typeof createOpencodeClient> // OpenCode SDK client
project: Project // Current project info
directory: string // Current working directory
worktree: string // Git worktree path
serverUrl: URL // Server URL
$: BunShell // Bun shell API
}
```
**Two hook mechanisms (important distinction):**
1. **Direct interceptor hooks** — keys on the returned `Hooks` object, receive `(input, output)` allowing mutation:
- `tool.execute.before`: `(input: { tool, sessionID, callID }, output: { args })`
- `tool.execute.after`: `(input: { tool, sessionID, callID, args }, output: { title, output, metadata })`
- `shell.env`, `chat.message`, `chat.params`, `chat.headers`, `permission.ask`, `command.execute.before`
- Experimental: `experimental.session.compacting`, `experimental.chat.messages.transform`, `experimental.chat.system.transform`
2. **Bus event catch-all** — generic `event` hook, receives `{ event }` where `event.type` is the event name:
- `session.created`, `session.compacted`, `session.deleted`, `session.idle`, `session.error`, `session.status`, `session.updated`, `session.diff`
- `message.updated`, `message.part.updated`, `message.part.removed`, `message.removed`
- `file.edited`, `file.watcher.updated`
- `command.executed`, `todo.updated`, `installation.updated`, `server.connected`
- `permission.asked`, `permission.replied`
- `lsp.client.diagnostics`, `lsp.updated`
- `tui.prompt.append`, `tui.command.execute`, `tui.toast.show`
- Total: **27 bus events** across **12 categories**
**Custom tool registration (CORRECTED — name is the key, not positional arg):**
```typescript
return {
tool: {
claude_mem_search: tool({
description: "Search claude-mem memory database",
args: { query: tool.schema.string() },
async execute(args, context) {
// context: { sessionID, messageID, agent, directory, worktree, abort, metadata, ask }
const response = await fetch(`http://localhost:37777/api/search?q=${encodeURIComponent(args.query)}`)
return await response.text()
},
}),
},
}
```
### What to implement
1. **Create OpenCode plugin** at `src/integrations/opencode-plugin/index.ts`:
- Export a `Plugin` function receiving full `PluginInput` context
- Use **direct interceptor** `tool.execute.after` for tool observation capture (gives `tool`, `args`, `output`)
- Use **bus event catch-all** `event` for session lifecycle:
| Mechanism | Event | Map to claude-mem |
|-----------|-------|-------------------|
| interceptor | `tool.execute.after` | `observation` (tool name + args + output) |
| bus event | `session.created` | `session-init` |
| bus event | `message.updated` | `observation` (assistant messages) |
| bus event | `session.compacted` | `summary` |
| bus event | `file.edited` | `observation` (file changes) |
| bus event | `session.deleted` | `session-end` |
- Register `claude_mem_search` custom tool using correct `tool({ description, args, execute })` API
- Hit `localhost:37777` API endpoints from the plugin
2. **Build the plugin** in the esbuild pipeline → `dist/opencode-plugin/index.js`
3. **Create OpenCode setup in installer** (two options, prefer file-based):
- **Option A (file-based):** Copy plugin to `~/.config/opencode/plugins/claude-mem.ts` (auto-loaded at startup)
- **Option B (npm-based):** Add to `~/.config/opencode/opencode.json` under `"plugin"` array: `["claude-mem"]`
- Config also supports JSONC (`opencode.jsonc`) and legacy `config.json`
- Context injection: Append to `~/.config/opencode/AGENTS.md` (or create it) with `<claude-mem-context>` tags
- Additional context via `"instructions"` config key (supports file paths, globs, remote URLs)
4. **Add OpenCode to installer IDE selection**
### OpenCode Verification
- `npx claude-mem install --ide opencode` registers the plugin (file or npm)
- OpenCode loads the plugin on next session
- `tool.execute.after` interceptor produces observations with `tool`, `args`, `output`
- Bus events (`session.created`, `session.deleted`) handle session lifecycle
- `claude_mem_search` custom tool works in OpenCode sessions
- Context is injected via AGENTS.md
### OpenCode Anti-patterns
- Do NOT try to use OpenCode's `session.diff` for full capture — it's a summary diff, not raw data
- Do NOT use `tool('name', schema, handler)` — wrong signature. Name is the key in the `tool:{}` map
- Do NOT assume bus events have the same `(input, output)` mutation pattern — they only receive `{ event }`
- OpenCode plugins run in Bun — the plugin CAN use Bun APIs (unlike the npx CLI itself)
- Do NOT hardcode `~/.config/opencode/` — respect `OPENCODE_CONFIG_DIR` env var if set
---
## Phase 5: Windsurf Integration (Tier 1 — Hook-Based)
**Why next**: 11 Cascade hooks, ~1M users. Hook architecture uses JSON stdin with a consistent envelope format.
### Verified Windsurf Hook Events (from docs.windsurf.com/windsurf/cascade/hooks)
**Naming pattern**: `pre_`/`post_` prefix + 5 action categories, plus 2 standalone post-only events.
| Event | Can Block? | Map to claude-mem | Use |
|-------|-----------|-------------------|-----|
| `pre_user_prompt` | Yes | `session-init` + `context` | Start session, inject context |
| `pre_read_code` | Yes | — | Skip (pre-execution, can block file reads) |
| `post_read_code` | No | — | Skip (too noisy, file reads are frequent) |
| `pre_write_code` | Yes | — | Skip (pre-execution, can block writes) |
| `post_write_code` | No | `observation` | Code generation |
| `pre_run_command` | Yes | — | Skip (pre-execution, can block commands) |
| `post_run_command` | No | `observation` | Shell command execution |
| `pre_mcp_tool_use` | Yes | — | Skip (pre-execution, can block MCP calls) |
| `post_mcp_tool_use` | No | `observation` | MCP tool results |
| `post_cascade_response` | No | `observation` | Full AI response |
| `post_setup_worktree` | No | — | Skip (informational) |
**Mapped**: 5 of 11 events (all post-action). **Skipped**: 4 pre-hooks (blocking-capable, pre-execution) + 2 low-value post-hooks.
### Verified Stdin Payload Schema
**Common envelope (all hooks):**
```json
{
"agent_action_name": "string",
"trajectory_id": "string",
"execution_id": "string",
"timestamp": "ISO 8601 string",
"tool_info": { /* event-specific payload */ }
}
```
**Event-specific `tool_info` payloads:**
| Event | `tool_info` fields |
|-------|-------------------|
| `pre_user_prompt` | `{ user_prompt: string }` |
| `pre_read_code` / `post_read_code` | `{ file_path: string }` |
| `pre_write_code` / `post_write_code` | `{ file_path: string, edits: [{ old_string: string, new_string: string }] }` |
| `pre_run_command` / `post_run_command` | `{ command_line: string, cwd: string }` |
| `pre_mcp_tool_use` | `{ mcp_server_name: string, mcp_tool_name: string, mcp_tool_arguments: {} }` |
| `post_mcp_tool_use` | `{ mcp_server_name: string, mcp_tool_name: string, mcp_tool_arguments: {}, mcp_result: string }` |
| `post_cascade_response` | `{ response: string }` (markdown) |
| `post_setup_worktree` | `{ worktree_path: string, root_workspace_path: string }` |
**Exit codes:** `0` = success, `2` = block (pre-hooks only; stderr shown to agent), any other = non-blocking warning.
### What to implement
1. **Create Windsurf platform adapter** at `src/cli/adapters/windsurf.ts`:
- Normalize Windsurf's hook input format to `NormalizedHookInput`
- Common envelope: `agent_action_name`, `trajectory_id`, `execution_id`, `timestamp`, `tool_info`
- Map: `trajectory_id` → `sessionId`, `tool_info` fields per event type
- For `post_write_code`: `tool_info.file_path` + `tool_info.edits` → file change observation
- For `post_run_command`: `tool_info.command_line` + `tool_info.cwd` → command observation
- For `post_mcp_tool_use`: `tool_info.mcp_tool_name` + `tool_info.mcp_tool_arguments` + `tool_info.mcp_result` → tool observation
- For `post_cascade_response`: `tool_info.response` → full AI response observation
2. **Create Windsurf hooks installer** at `src/services/integrations/WindsurfHooksInstaller.ts`:
- Write hooks to `~/.codeium/windsurf/hooks.json` (user-level, for global coverage)
- Per-workspace override at `.windsurf/hooks.json` if user chooses workspace-level install
- Config format (verified):
```json
{
"hooks": {
"post_write_code": [{
"command": "<path-to-hook-script>",
"show_output": false,
"working_directory": "<optional>"
}]
}
}
```
- Note: Tilde expansion (`~`) is NOT supported in `working_directory` — use absolute paths
- Merge order: cloud → system → user → workspace (all hooks at all levels execute)
- Context injection via `.windsurf/rules/claude-mem-context.md` (workspace-level; Windsurf rules are workspace-scoped)
- Rule limits: 6,000 chars per file, 12,000 chars total across all rules
3. **Register `windsurf` in `getPlatformAdapter()`** at `src/cli/adapters/index.ts`
4. **Add Windsurf to installer IDE selection**
### Windsurf Verification
- `npx claude-mem install --ide windsurf` creates hooks config at `~/.codeium/windsurf/hooks.json`
- Windsurf sessions are captured by the worker via post-action hooks
- `trajectory_id` is used as session identifier
- Context is injected via `.windsurf/rules/claude-mem-context.md` (under 6K char limit)
- Existing hooks.json is preserved (merge, not overwrite)
### Windsurf Anti-patterns
- Do NOT use fabricated event names (`post_search_code`, `post_lint_code`, `on_error`, `pre_tool_execution`) — they don't exist
- Do NOT assume Windsurf's stdin JSON matches Claude Code's — it uses `tool_info` envelope, not flat fields
- Do NOT use tilde (`~`) in `working_directory` — not supported, use absolute paths
- Do NOT exceed 6K chars in the context rule file — Windsurf truncates beyond that
- Pre-hooks can block actions (exit 2) — only use post-hooks for observation capture
---
## Phase 6: Codex CLI Integration (Tier 1 — Hook + Transcript)
### Dedup strategy
Codex has both a `notify` hook (real-time) and transcript files (complete history). Use **transcript watching only** — it's more complete and avoids the complexity of dual capture paths. The `notify` hook is a simpler mechanism that doesn't provide enough granularity to justify maintaining two integration paths. If transcript watching proves insufficient, add the notify hook later.
### What to implement
1. **Create Codex transcript schema** — the sample in `src/services/transcripts/config.ts` is already production-quality. Verify against current Codex CLI JSONL format and update if needed.
2. **Create Codex setup in installer**:
- Write transcript-watch config to `~/.claude-mem/transcript-watch.json`
- Set up watch for `~/.codex/sessions/**/*.jsonl` using existing CODEX_SAMPLE_SCHEMA
- Context injection via `.codex/AGENTS.md` (Codex reads this natively)
- Must merge with existing `config.toml` if it exists (read → parse → merge → write)
3. **Add Codex CLI to installer IDE selection**
### Verification
- `npx claude-mem install --ide codex` creates transcript watch config
- Codex sessions appear in claude-mem database
- `AGENTS.md` updated with context after sessions
- Existing `config.toml` is preserved
---
## Phase 7: OpenClaw Integration (Tier 1 — Plugin-Based)
**Plugin is already fully built** at `openclaw/src/index.ts` (~1000 lines). Has event hooks, SSE observation feed, MEMORY.md sync, slash commands. Only wiring into the installer is needed.
### What to implement
1. **Wire OpenClaw into the npx installer**:
- Detect `~/.openclaw/` directory
- Copy pre-built plugin from `openclaw/dist/` (built in Phase 2) to OpenClaw plugins location
- Register in `~/.openclaw/openclaw.json` under `plugins.claude-mem`
- Configure worker port, project name, syncMemoryFile
- Optionally prompt for observation feed setup (channel type + target ID)
2. **Add OpenClaw to IDE selection TUI** with hint about messaging channel support
### Verification
- `npx claude-mem install --ide openclaw` registers the plugin
- OpenClaw gateway loads the plugin on restart
- Observations are recorded from OpenClaw sessions
- MEMORY.md syncs to agent workspaces
### Anti-patterns
- Do NOT rebuild the OpenClaw plugin from source at install time — it ships pre-built from Phase 2
- Do NOT modify the plugin's event handling — it's battle-tested
---
## Phase 8: MCP-Based Integrations (Tier 2)
**These get the MCP server for free** — it already exists at `plugin/scripts/mcp-server.cjs`. The installer just needs to write the right config files per IDE.
MCP-only integrations provide: search tools + context injection. They do NOT capture transcripts or tool usage in real-time.
### What to implement
1. **Copilot CLI MCP setup**:
- Write MCP config to `~/.copilot/config` (merge, not overwrite)
- Context injection: `.github/copilot-instructions.md`
- Detection: `copilot` command in PATH
2. **Antigravity MCP setup**:
- Write MCP config to `~/.gemini/antigravity/mcp_config.json` (merge, not overwrite)
- Context injection: `~/.gemini/GEMINI.md` (shared with Gemini CLI) and/or `.agent/rules/claude-mem-context.md`
- Detection: `~/.gemini/antigravity/` exists
- Note: Antigravity has NO hook system — MCP is the only integration path
3. **Goose MCP setup**:
- Write MCP config to `~/.config/goose/config.yaml` (YAML merge — use a lightweight YAML parser or write the block manually if config doesn't exist)
- Detection: `~/.config/goose/` exists OR `goose` in PATH
- Note: Goose co-developed MCP with Anthropic, so MCP support is excellent
4. **Crush MCP setup**:
- Write MCP config to Crush's JSON config
- Detection: `crush` in PATH
5. **Roo Code MCP setup**:
- Write MCP config to `.roo/` or workspace settings
- Context injection: `.roo/rules/claude-mem-context.md`
- Detection: Check for VS Code extension directory containing `roo-code`
6. **Warp MCP setup**:
- Warp uses `WARP.md` in project root for context injection (similar to CLAUDE.md)
- MCP servers configured via Warp Drive UI, but also via config files
- Detection: `~/.warp/` exists OR `warp` in PATH
- Note: Warp is a terminal replacement (~26k stars), not just a CLI tool — multi-agent orchestration with management UI
7. **For each**: Add to installer IDE detection and selection
### Config merging strategy
JSON configs: Read → parse → deep merge → write back. YAML configs (Goose): If file exists, read and append the MCP block. If not, create from template. Avoid pulling in a full YAML parser library — write the MCP block as a string append with proper indentation if the format is predictable.
### Verification
- Each IDE can search claude-mem via MCP tools
- Context files are written to IDE-specific locations
- Existing configs are preserved
### Anti-patterns
- MCP-only integrations do NOT capture transcripts — don't claim "full integration"
- Do NOT overwrite existing config files — always merge
- Do NOT add a heavy YAML parser dependency for one integration
---
## Phase 9: Remove Old Installer
This is a **full replacement**, not a deprecation.
### What to implement
1. Remove `claude-mem-installer` npm package (unpublish or mark deprecated with message pointing to `npx claude-mem`)
2. Update `install/public/install.sh` → redirect to `npx claude-mem`
3. Remove `installer/` directory from the repository (it's replaced by `src/npx-cli/`)
4. Update docs site to reflect the new install command
5. Update README.md install instructions
---
## Phase 10: Final Verification
### All platforms (macOS, Linux, Windows)
1. `npm run build` succeeds, produces `dist/cli/index.js` and `openclaw/dist/index.js`
2. `node dist/cli/index.js install` works clean (no prior install)
3. Auto-detects installed IDEs correctly per platform
4. `npx claude-mem start/stop/status/search` all work
5. `npx claude-mem update` updates correctly
6. `npx claude-mem uninstall` cleans up all IDE configs
7. `npx claude-mem version` prints version
8. `npx claude-mem start` before install shows helpful error
9. No Bun dependency at install time
### Per-integration verification
| Integration | Type | Captures Sessions | Search via MCP | Context Injection |
|-------------|------|-------------------|----------------|-------------------|
| Claude Code | Plugin | Yes (hooks) | Yes | CLAUDE.md |
| Gemini CLI | Hooks | Yes (AfterTool, AfterAgent) | Yes (via hook) | GEMINI.md |
| OpenCode | Plugin | Yes (tool.execute.after, message.updated) | Yes (custom tool) | AGENTS.md / rules |
| Windsurf | Hooks | Yes (post_cascade_response, etc.) | Yes (via hook) | .windsurf/rules/ |
| Codex CLI | Transcript | Yes (JSONL watcher) | No (passive only) | .codex/AGENTS.md |
| OpenClaw | Plugin | Yes (event hooks) | Yes (slash commands) | MEMORY.md |
| Copilot CLI | MCP | No | Yes | copilot-instructions.md |
| Antigravity | MCP | No | Yes | .agent/rules/ |
| Goose | MCP | No | Yes | MCP context |
| Crush | MCP | No | Yes | Skills |
| Roo Code | MCP | No | Yes | .roo/rules/ |
| Warp | MCP | No | Yes | WARP.md |
---
## Priority Order & Impact
| Phase | IDE/Tool | Integration Type | Stars/Users | Effort |
|-------|----------|-----------------|-------------|--------|
| 1-2 | (infrastructure) | npx CLI + build pipeline | All users | Medium |
| 3 | Gemini CLI | Hooks (Tier 1) | ~95k stars | Medium (near-identical to Claude Code) |
| 4 | OpenCode | Plugin (Tier 1) | ~110k stars | Medium (rich plugin SDK) |
| 5 | Windsurf | Hooks (Tier 1) | ~1M users | Medium |
| 6 | Codex CLI | Transcript (Tier 3) | Growing (OpenAI) | Low (schema already exists) |
| 7 | OpenClaw | Plugin (Tier 1) — pre-built | ~196k stars | Low (wire into installer) |
| 8 | Copilot CLI, Antigravity, Goose, Crush, Warp, Roo Code | MCP (Tier 2) | 20M+ combined | Low per IDE |
| 9 | (remove old installer) | — | — | Low |
| 10 | (final verification) | — | — | Low |
## Out of Scope
- **Removing Bun as runtime dependency**: Worker still requires Bun for `bun:sqlite`. Runtime commands delegate to Bun; install commands don't need it.
- **JetBrains plugin**: Requires Kotlin/Java development — different ecosystem entirely.
- **Zed extension**: WASM sandbox limits feasibility.
- **Neovim/Emacs plugins**: Niche audiences, complex plugin ecosystems (Lua/Elisp). Could be added later via MCP (gptel supports it).
- **Amazon Q / Kiro**: Amazon Q Developer CLI has been sunsetted in favor of Kiro (proprietary, no public extensibility API yet). Revisit when Kiro opens up.
- **Aider**: Niche audience, writes Markdown transcripts (not JSONL), would require a markdown parser mode in the watcher. Add if demand materializes.
- **Continue.dev**: Small user base relative to other MCP tools. Can be added as a Tier 2 MCP integration later if requested.
- **Toad / Qwen Code / Oh-my-pi**: Too early-stage or too niche. Monitor for growth.
- **OpenClaw plugin development**: The plugin is already complete. Only installer wiring is in scope.

116
.agent/services/claude-mem/.translation-cache.json Normal file
View File

@@ -0,0 +1,116 @@
{
"sourceHash": "9ab0d799179c66f9",
"lastUpdated": "2025-12-12T07:42:03.489Z",
"translations": {
"zh": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.12256679999999998
},
"ja": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.12973164999999998
},
"pt-br": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.11508539999999999
},
"ko": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.13952664999999997
},
"es": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.12530165
},
"de": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.12232164999999998
},
"fr": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:06:55.026Z",
"costUsd": 0.11906665
},
"he": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.151329
},
"ar": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.151952
},
"ru": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.13418499999999997
},
"pl": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.13196799999999997
},
"cs": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.12714599999999998
},
"nl": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.118389
},
"tr": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.13991199999999998
},
"uk": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:25:00.076Z",
"costUsd": 0.13786
},
"vi": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.15467299999999998
},
"id": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.185581
},
"th": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.177859
},
"hi": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.17412700000000003
},
"bn": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.202735
},
"ro": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.12212875
},
"sv": {
"hash": "9ab0d799179c66f9",
"translatedAt": "2025-12-12T07:42:03.489Z",
"costUsd": 0.12143675000000001
}
}
}

1113
.agent/services/claude-mem/CHANGELOG.md Normal file
View File

File diff suppressed because it is too large Load Diff

94
.agent/services/claude-mem/CLAUDE.md Normal file
View File

@@ -0,0 +1,94 @@
# Claude-Mem: AI Development Instructions
Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.
## Architecture
**5 Lifecycle Hooks**: SessionStart → UserPromptSubmit → PostToolUse → Summary → SessionEnd
**Hooks** (`src/hooks/*.ts`) - TypeScript → ESM, built to `plugin/scripts/*-hook.js`
**Worker Service** (`src/services/worker-service.ts`) - Express API on port 37777, Bun-managed, handles AI processing asynchronously
**Database** (`src/services/sqlite/`) - SQLite3 at `~/.claude-mem/claude-mem.db`
**Search Skill** (`plugin/skills/mem-search/SKILL.md`) - HTTP API for searching past work, auto-invoked when users ask about history
**Planning Skill** (`plugin/skills/make-plan/SKILL.md`) - Orchestrator instructions for creating phased implementation plans with documentation discovery
**Execution Skill** (`plugin/skills/do/SKILL.md`) - Orchestrator instructions for executing phased plans using subagents
**Chroma** (`src/services/sync/ChromaSync.ts`) - Vector embeddings for semantic search
**Viewer UI** (`src/ui/viewer/`) - React interface at http://localhost:37777, built to `plugin/ui/viewer.html`
## Privacy Tags
- `<private>content</private>` - User-level privacy control (manual, prevents storage)
**Implementation**: Tag stripping happens at hook layer (edge processing) before data reaches worker/database. See `src/utils/tag-stripping.ts` for shared utilities.
## Build Commands
```bash
npm run build-and-sync # Build, sync to marketplace, restart worker
```
## Configuration
Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created with defaults on first run.
## File Locations
- **Source**: `<project-root>/src/`
- **Built Plugin**: `<project-root>/plugin/`
- **Installed Plugin**: `~/.claude/plugins/marketplaces/thedotmack/`
- **Database**: `~/.claude-mem/claude-mem.db`
- **Chroma**: `~/.claude-mem/chroma/`
## Exit Code Strategy
Claude-mem hooks use specific exit codes per Claude Code's hook contract:
- **Exit 0**: Success or graceful shutdown (Windows Terminal closes tabs)
- **Exit 1**: Non-blocking error (stderr shown to user, continues)
- **Exit 2**: Blocking error (stderr fed to Claude for processing)
**Philosophy**: Worker/hook errors exit with code 0 to prevent Windows Terminal tab accumulation. The wrapper/plugin layer handles restart logic. ERROR-level logging is maintained for diagnostics.
See `private/context/claude-code/exit-codes.md` for full hook behavior matrix.
## Requirements
- **Bun** (all platforms - auto-installed if missing)
- **uv** (all platforms - auto-installed if missing, provides Python for Chroma)
- Node.js
## Documentation
**Public Docs**: https://docs.claude-mem.ai (Mintlify)
**Source**: `docs/public/` - MDX files, edit `docs.json` for navigation
**Deploy**: Auto-deploys from GitHub on push to main
## Pro Features Architecture
Claude-mem is designed with a clean separation between open-source core functionality and optional Pro features.
**Open-Source Core** (this repository):
- All worker API endpoints on localhost:37777 remain fully open and accessible
- Pro features are headless - no proprietary UI elements in this codebase
- Pro integration points are minimal: settings for license keys, tunnel provisioning logic
- The architecture ensures Pro features extend rather than replace core functionality
**Pro Features** (coming soon, external):
- Enhanced UI (Memory Stream) connects to the same localhost:37777 endpoints as the open viewer
- Additional features like advanced filtering, timeline scrubbing, and search tools
- Access gated by license validation, not by modifying core endpoints
- Users without Pro licenses continue using the full open-source viewer UI without limitation
This architecture preserves the open-source nature of the project while enabling sustainable development through optional paid features.
## Important
No need to edit the changelog ever, it's generated automatically.

630
.agent/services/claude-mem/LICENSE Normal file
View File

@@ -0,0 +1,630 @@
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Preamble
The GNU Affero General Public License is a free, copyleft license for
software and other kinds of works, specifically designed to ensure
cooperation with the community in the case of network server software.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
our General Public Licenses are intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
Developers that use our General Public Licenses protect your rights
with two steps: (1) assert copyright on the software, and (2) offer
you this License which gives you legal permission to copy, distribute
and/or modify the software.
A secondary benefit of defending all users' freedom is that
improvements made in alternate versions of the program, if they
receive widespread use, become available for other developers to
incorporate. Many developers of free software are heartened and
encouraged by the resulting cooperation. However, in the case of
software used on network servers, this result may fail to come about.
The GNU General Public License permits making a modified version and
letting the public access it on a server without ever releasing its
source code to the public.
The GNU Affero General Public License is designed specifically to
ensure that, in such cases, the modified source code becomes available
to the community. It requires the operator of a network server to
provide the source code of the modified version running there to the
users of that server. Therefore, public use of a modified version, on
a publicly accessible server, gives the public access to the source
code of the modified version.
An older license, called the Affero General Public License and
published by Affero, was designed to accomplish similar goals. This is
a different license, not a version of the Affero GPL, but Affero has
released a new version of the Affero GPL which permits relicensing under
this license.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU Affero General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Remote Network Interaction; Use with the GNU General Public License.
Notwithstanding any other provision of this License, if you modify the
Program, your modified version must prominently offer all users
interacting with it remotely through a computer network (if your version
supports such interaction) an opportunity to receive the Corresponding
Source of your version by providing access to the Corresponding Source
from a network server at no charge, through some standard or customary
means of facilitating copying of software. This Corresponding Source
shall include the Corresponding Source for any work covered by version 3
of the GNU General Public License that is incorporated pursuant to the
following paragraph.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the work with which it is combined will remain governed by version
3 of the GNU General Public License.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU Affero General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU Affero General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU Affero General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU Affero General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS

365
.agent/services/claude-mem/README.md Normal file
View File

@@ -0,0 +1,365 @@
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="docs/i18n/README.zh.md">🇨🇳 中文</a> •
<a href="docs/i18n/README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •
<a href="docs/i18n/README.pt.md">🇵🇹 Português</a> •
<a href="docs/i18n/README.pt-br.md">🇧🇷 Português</a> •
<a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
<a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
<a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
<a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •
<a href="docs/i18n/README.he.md">🇮🇱 עברית</a> •
<a href="docs/i18n/README.ar.md">🇸🇦 العربية</a> •
<a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •
<a href="docs/i18n/README.pl.md">🇵🇱 Polski</a> •
<a href="docs/i18n/README.cs.md">🇨🇿 Čeština</a> •
<a href="docs/i18n/README.nl.md">🇳🇱 Nederlands</a> •
<a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a> •
<a href="docs/i18n/README.uk.md">🇺🇦 Українська</a> •
<a href="docs/i18n/README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="docs/i18n/README.tl.md">🇵🇭 Tagalog</a> •
<a href="docs/i18n/README.id.md">🇮🇩 Indonesia</a> •
<a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •
<a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
<a href="docs/i18n/README.bn.md">🇧🇩 বাংলা</a> •
<a href="docs/i18n/README.ur.md">🇵🇰 اردو</a> •
<a href="docs/i18n/README.ro.md">🇷🇴 Română</a> •
<a href="docs/i18n/README.sv.md">🇸🇪 Svenska</a> •
<a href="docs/i18n/README.it.md">🇮🇹 Italiano</a> •
<a href="docs/i18n/README.el.md">🇬🇷 Ελληνικά</a> •
<a href="docs/i18n/README.hu.md">🇭🇺 Magyar</a> •
<a href="docs/i18n/README.fi.md">🇫🇮 Suomi</a> •
<a href="docs/i18n/README.da.md">🇩🇰 Dansk</a> •
<a href="docs/i18n/README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Persistent memory compression system built for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<table align="center">
<tr>
<td align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img
src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif"
alt="Claude-Mem Preview"
width="500"
>
</picture>
</a>
</td>
<td align="center">
<a href="https://www.star-history.com/#thedotmack/claude-mem&Date">
<picture>
<source
media="(prefers-color-scheme: dark)"
srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&theme=dark&legend=top-left"
/>
<source
media="(prefers-color-scheme: light)"
srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
/>
<img
alt="Star History Chart"
src="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
width="500"
/>
</picture>
</a>
</td>
</tr>
</table>
<p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#how-it-works">How It Works</a> •
<a href="#mcp-search-tools">Search Tools</a> •
<a href="#documentation">Documentation</a> •
<a href="#configuration">Configuration</a> •
<a href="#troubleshooting">Troubleshooting</a> •
<a href="#license">License</a>
</p>
<p align="center">
Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.
</p>
---
## Quick Start
Start a new Claude Code session in the terminal and enter the following commands:
```
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```
Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
> **Note:** Claude-Mem is also published on npm, but `npm install -g claude-mem` installs the **SDK/library only** — it does not register the plugin hooks or set up the worker service. To use Claude-Mem as a plugin, always install via the `/plugin` commands above.
### 🦞 OpenClaw Gateway
Install claude-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai) gateways with a single command:
```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```
The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the [OpenClaw Integration Guide](https://docs.claude-mem.ai/openclaw-integration) for details.
**Key Features:**
- 🧠 **Persistent Memory** - Context survives across sessions
- 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility
- 🔍 **Skill-Based Search** - Query your project history with mem-search skill
- 🖥️ **Web Viewer UI** - Real-time memory stream at http://localhost:37777
- 💻 **Claude Desktop Skill** - Search memory from Claude Desktop conversations
- 🔒 **Privacy Control** - Use `<private>` tags to exclude sensitive content from storage
- ⚙️ **Context Configuration** - Fine-grained control over what context gets injected
- 🤖 **Automatic Operation** - No manual intervention required
- 🔗 **Citations** - Reference past observations with IDs (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)
- 🧪 **Beta Channel** - Try experimental features like Endless Mode via version switching
---
## Documentation
📚 **[View Full Documentation](https://docs.claude-mem.ai/)** - Browse on official website
### Getting Started
- **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation
- **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically
- **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language
- **[Beta Features](https://docs.claude-mem.ai/beta-features)** - Try experimental features like Endless Mode
### Best Practices
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI agent context optimization principles
- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophy behind Claude-Mem's context priming strategy
### Architecture
- **[Overview](https://docs.claude-mem.ai/architecture/overview)** - System components & data flow
- **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5
- **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks
- **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management
- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search
- **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database
### Configuration & Development
- **[Configuration](https://docs.claude-mem.ai/configuration)** - Environment variables & settings
- **[Development](https://docs.claude-mem.ai/development)** - Building, testing, contributing
- **[Troubleshooting](https://docs.claude-mem.ai/troubleshooting)** - Common issues & solutions
---
## How It Works
**Core Components:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook)
3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
4. **SQLite Database** - Stores sessions, observations, summaries
5. **mem-search Skill** - Natural language queries with progressive disclosure
6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) for details.
---
## MCP Search Tools
Claude-Mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**:
**The 3-Layer Workflow:**
1. **`search`** - Get compact index with IDs (~50-100 tokens/result)
2. **`timeline`** - Get chronological context around interesting results
3. **`get_observations`** - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)
**How It Works:**
- Claude uses MCP tools to search your memory
- Start with `search` to get an index of results
- Use `timeline` to see what was happening around specific observations
- Use `get_observations` to fetch full details for relevant IDs
- **~10x token savings** by filtering before fetching details
**Available MCP Tools:**
1. **`search`** - Search memory index with full-text queries, filters by type/date/project
2. **`timeline`** - Get chronological context around a specific observation or query
3. **`get_observations`** - Fetch full observation details by IDs (always batch multiple IDs)
**Example Usage:**
```typescript
// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
// Step 3: Fetch full details
get_observations(ids=[123, 456])
```
See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples.
---
## Beta Features
Claude-Mem offers a **beta channel** with experimental features like **Endless Mode** (biomimetic memory architecture for extended sessions). Switch between stable and beta versions from the web viewer UI at http://localhost:37777 → Settings.
See **[Beta Features Documentation](https://docs.claude-mem.ai/beta-features)** for details on Endless Mode and how to try it.
---
## System Requirements
- **Node.js**: 18.0.0 or higher
- **Claude Code**: Latest version with plugin support
- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
- **uv**: Python package manager for vector search (auto-installed if missing)
- **SQLite 3**: For persistent storage (bundled)
---
### Windows Setup Notes
If you see an error like:
```powershell
npm : The term 'npm' is not recognized as the name of a cmdlet
```
Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation.
---
## Configuration
Settings are managed in `~/.claude-mem/settings.json` (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings.
See the **[Configuration Guide](https://docs.claude-mem.ai/configuration)** for all available settings and examples.
---
## Development
See the **[Development Guide](https://docs.claude-mem.ai/development)** for build instructions, testing, and contribution workflow.
---
## Troubleshooting
If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.
See the **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** for common issues and solutions.
---
## Bug Reports
Create comprehensive bug reports with the automated generator:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Update documentation
5. Submit a Pull Request
See [Development Guide](https://docs.claude-mem.ai/development) for contribution workflow.
---
## License
This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
See the [LICENSE](LICENSE) file for full details.
**What This Means:**
- You can use, modify, and distribute this software freely
- If you modify and deploy on a network server, you must make your source code available
- Derivative works must also be licensed under AGPL-3.0
- There is NO WARRANTY for this software
**Note on Ragtime**: The `ragtime/` directory is licensed separately under the **PolyForm Noncommercial License 1.0.0**. See [ragtime/LICENSE](ragtime/LICENSE) for details.
---
## Support
- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory)
- **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu)
- **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**
---
### What About $CMEM?
$CMEM is a solana token created by a 3rd party without Claude-Mem's prior consent, but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing real-time agent data to the developers and knowledge workers that need it most. $CMEM: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS

6
.agent/services/claude-mem/conductor.json Normal file
View File

@@ -0,0 +1,6 @@
{
"scripts": {
"setup": "cp ../settings.local.json .claude/settings.local.json && npm install",
"run": "npm run build-and-sync"
}
}

3
.agent/services/claude-mem/cursor-hooks/.gitignore vendored Normal file
View File

@@ -0,0 +1,3 @@
# Ignore backup files created by sed
*.bak

173
.agent/services/claude-mem/cursor-hooks/CONTEXT-INJECTION.md Normal file
View File

@@ -0,0 +1,173 @@
# Context Injection in Cursor Hooks
## The Solution: Auto-Updated Rules File
Context is automatically injected via Cursor's **Rules** system:
1. **Install**: `claude-mem cursor install` creates initial context file
2. **Stop hook**: `session-summary.sh` updates context after each session ends
3. **Cursor**: Automatically includes `.cursor/rules/claude-mem-context.mdc` in all chats
**Result**: Context appears at the start of every conversation, just like Claude Code!
## How It Works
### Installation Creates Initial Context
```bash
claude-mem cursor install
```
This:
1. Copies hook scripts to `.cursor/hooks/`
2. Creates `hooks.json` configuration
3. Fetches existing context from claude-mem and writes to `.cursor/rules/claude-mem-context.mdc`
### Context Updates at Three Points
Context is refreshed **three times** per session for maximum freshness:
1. **Before prompt submission** (`context-inject.sh`): Ensures you start with the latest context from previous sessions
2. **After summary completes** (worker auto-update): Immediately after the summary is saved, worker updates the context file
3. **After session ends** (`session-summary.sh`): Fallback update in case worker update was missed
### Before Prompt Hook Updates Context
When you submit a prompt, `context-inject.sh`:
```bash
# 1. Ensure worker is running
ensure_worker_running "$worker_port"
# 2. Fetch fresh context
context=$(curl -s ".../api/context/inject?project=...")
# 3. Write to rules file (used immediately by Cursor)
cat > .cursor/rules/claude-mem-context.mdc << EOF
---
alwaysApply: true
---
# Memory Context
${context}
EOF
```
### Stop Hook Updates Context
After each session ends, `session-summary.sh`:
```bash
# 1. Generate session summary
curl -X POST .../api/sessions/summarize
# 2. Fetch fresh context (includes new observations)
context=$(curl -s ".../api/context/inject?project=...")
# 3. Write to rules file for next session
cat > .cursor/rules/claude-mem-context.mdc << EOF
---
alwaysApply: true
---
# Memory Context
${context}
EOF
```
### The Rules File
Located at: `.cursor/rules/claude-mem-context.mdc`
```markdown
---
alwaysApply: true
description: "Claude-mem context from past sessions (auto-updated)"
---
# Memory Context from Past Sessions
[Your context from claude-mem appears here]
---
*Updated after last session.*
```
### Update Flow
Context updates at **three points**:
**Before each prompt:**
1. User submits a prompt
2. `beforeSubmitPrompt` hook runs `context-inject.sh`
3. Context file refreshed with latest observations from previous sessions
4. Cursor reads the updated rules file
**After summary completes (worker auto-update):**
1. Summary is saved to database
2. Worker checks if project is registered for Cursor
3. If yes, immediately writes updated context file with new observations
4. No hook involved - happens in the worker process
**After session ends (fallback):**
1. Agent completes (loop ends)
2. `stop` hook runs `session-summary.sh`
3. Context file updated (ensures nothing was missed)
4. Ready for next session
## Project Registry
When you run `claude-mem cursor install`, the project is registered in `~/.claude-mem/cursor-projects.json`. This allows the worker to automatically update your context file whenever a new summary is generated - even if it happens from Claude Code or another IDE working on the same project.
To see registered projects:
```bash
cat ~/.claude-mem/cursor-projects.json
```
## Comparison with Claude Code
| Feature | Claude Code | Cursor |
|---------|-------------|--------|
| Context injection | ✅ `additionalContext` in hook output | ✅ Auto-updated rules file |
| Injection timing | Immediate (same prompt) | Before prompt + after summary + after session |
| Persistence | Session only | File-based (persists across restarts) |
| Initial setup | Automatic | `claude-mem cursor install` creates initial context |
| MCP tool access | ✅ Full support | ✅ Full support |
| Web viewer | ✅ Available | ✅ Available |
## First Session Behavior
When you run `claude-mem cursor install`:
- If worker is running with existing memory → initial context is generated
- If no existing memory → placeholder file created
Context is then automatically refreshed:
- Before each prompt (ensures latest observations are included)
- After each session ends (captures new observations from the session)
## Additional Access Methods
### 1. MCP Tools
Configure claude-mem's MCP server in Cursor for search tools:
- `search(query, project, limit)`
- `timeline(anchor, depth_before, depth_after)`
- `get_observations(ids)`
### 2. Web Viewer
Access context manually at `http://localhost:37777`
### 3. Manual Request
Ask the agent: "Check claude-mem for any previous work on authentication"
## File Location
The context file is created at:
```
<workspace>/.cursor/rules/claude-mem-context.mdc
```
This is version-controlled by default. Add to `.gitignore` if you don't want to commit it:
```
.cursor/rules/claude-mem-context.mdc
```

251
.agent/services/claude-mem/cursor-hooks/INTEGRATION.md Normal file
View File

@@ -0,0 +1,251 @@
# Claude-Mem ↔ Cursor Integration Architecture
## Overview
This integration connects claude-mem's persistent memory system to Cursor's hook system, enabling:
- Automatic capture of agent actions (MCP tools, shell commands, file edits)
- Context retrieval from past sessions
- Session summarization for future reference
## Architecture
```
┌─────────────┐
│ Cursor │
│ Agent │
└──────┬──────┘
│
│ Events (MCP, Shell, File Edits, Prompts)
│
▼
┌─────────────────────────────────────┐
│ Cursor Hooks System │
│ ┌────────────────────────────────┐ │
│ │ beforeSubmitPrompt │ │
│ │ afterMCPExecution │ │
│ │ afterShellExecution │ │
│ │ afterFileEdit │ │
│ │ stop │ │
│ └────────────────────────────────┘ │
└──────┬──────────────────────────────┘
│
│ HTTP Requests
│
▼
┌─────────────────────────────────────┐
│ Hook Scripts (Bash) │
│ ┌────────────────────────────────┐ │
│ │ session-init.sh │ │
│ │ context-inject.sh │ │
│ │ save-observation.sh │ │
│ │ save-file-edit.sh │ │
│ │ session-summary.sh │ │
│ └────────────────────────────────┘ │
└──────┬──────────────────────────────┘
│
│ HTTP API Calls
│
▼
┌─────────────────────────────────────┐
│ Claude-Mem Worker Service │
│ (Port 37777) │
│ ┌────────────────────────────────┐ │
│ │ /api/sessions/init │ │
│ │ /api/sessions/observations │ │
│ │ /api/sessions/summarize │ │
│ │ /api/context/inject │ │
│ └────────────────────────────────┘ │
└──────┬──────────────────────────────┘
│
│ Database Operations
│
▼
┌─────────────────────────────────────┐
│ SQLite Database │
│ + Chroma Vector DB │
└─────────────────────────────────────┘
```
## Event Flow
### 1. Prompt Submission Flow
```
User submits prompt
↓
beforeSubmitPrompt hook fires
↓
session-init.sh
├─ Extract conversation_id, project name
├─ POST /api/sessions/init
└─ Initialize session in claude-mem
↓
context-inject.sh
├─ GET /api/context/inject?project=...
└─ Fetch relevant context (for future use)
↓
Prompt proceeds to agent
```
### 2. Tool Execution Flow
```
Agent executes MCP tool or shell command
↓
afterMCPExecution / afterShellExecution hook fires
↓
save-observation.sh
├─ Extract tool_name, tool_input, tool_response
├─ Map to claude-mem observation format
├─ POST /api/sessions/observations
└─ Store observation in database
```
### 3. File Edit Flow
```
Agent edits file
↓
afterFileEdit hook fires
↓
save-file-edit.sh
├─ Extract file_path, edits
├─ Create "write_file" observation
├─ POST /api/sessions/observations
└─ Store file edit observation
```
### 4. Session End Flow
```
Agent loop ends
↓
stop hook fires
↓
session-summary.sh
├─ POST /api/sessions/summarize
└─ Generate session summary for future retrieval
```
## Data Mapping
### Session ID Mapping
| Cursor Field | Claude-Mem Field | Notes |
|-------------|------------------|-------|
| `conversation_id` | `contentSessionId` | Stable across turns, used as primary session identifier |
| `generation_id` | (fallback) | Used if conversation_id unavailable |
### Tool Mapping
| Cursor Event | Claude-Mem Tool Name | Input Format |
|-------------|---------------------|--------------|
| `afterMCPExecution` | `tool_name` from event | `tool_input` as JSON |
| `afterShellExecution` | `"Bash"` | `{command: "..."}` |
| `afterFileEdit` | `"write_file"` | `{file_path: "...", edits: [...]}` |
### Project Mapping
| Source | Target | Notes |
|--------|--------|-------|
| `workspace_roots[0]` | Project name | Basename of workspace root directory |
## API Endpoints Used
### Session Management
- `POST /api/sessions/init` - Initialize new session
- `POST /api/sessions/summarize` - Generate session summary
### Observation Storage
- `POST /api/sessions/observations` - Store tool usage observation
### Context Retrieval
- `GET /api/context/inject?project=...` - Get relevant context for injection
### Health Checks
- `GET /api/readiness` - Check if worker is ready
## Configuration
### Worker Settings
Located in `~/.claude-mem/settings.json`:
- `CLAUDE_MEM_WORKER_PORT` (default: 37777)
- `CLAUDE_MEM_WORKER_HOST` (default: 127.0.0.1)
### Hook Settings
Located in `hooks.json`:
- Hook event names
- Script paths (relative or absolute)
## Error Handling
### Worker Unavailable
- Hooks poll `/api/readiness` with 30 retries (6 seconds)
- If worker unavailable, hooks fail gracefully (exit 0)
- Observations are fire-and-forget (curl errors ignored)
### Missing Data
- Empty `conversation_id` → use `generation_id`
- Empty `workspace_root` → use `pwd`
- Missing tool data → skip observation
### Network Errors
- All HTTP requests use `curl -s` (silent)
- Errors redirected to `/dev/null`
- Hooks always exit 0 to avoid blocking Cursor
## Limitations
1. **Context Injection**: Cursor's `beforeSubmitPrompt` doesn't support prompt modification. Context must be retrieved via:
- MCP tools (claude-mem provides search tools)
- Manual retrieval from web viewer
- Future: Agent SDK integration
2. **Transcript Access**: Cursor hooks don't provide transcript paths, limiting summary quality compared to Claude Code integration.
3. **Session Model**: Uses `conversation_id` which may not perfectly match Claude Code's session model.
4. **Tab Hooks**: Currently only supports Agent hooks. Tab (inline completion) hooks could be added separately.
## Future Enhancements
- [ ] Enhanced context injection via MCP tools
- [ ] Support for `beforeTabFileRead` and `afterTabFileEdit` hooks
- [ ] Better error reporting and logging
- [ ] Integration with Cursor's agent SDK
- [ ] Support for blocking/approval workflows
- [ ] Real-time context injection via agent messages
## Testing
### Manual Testing
1. **Test session initialization**:
```bash
echo '{"conversation_id":"test-123","workspace_roots":["/tmp/test"],"prompt":"test"}' | \
~/.cursor/hooks/session-init.sh
```
2. **Test observation capture**:
```bash
echo '{"conversation_id":"test-123","hook_event_name":"afterMCPExecution","tool_name":"test","tool_input":{},"result_json":{}}' | \
~/.cursor/hooks/save-observation.sh
```
3. **Test context retrieval**:
```bash
curl "http://127.0.0.1:37777/api/context/inject?project=test"
```
### Integration Testing
1. Enable hooks in Cursor
2. Submit a prompt
3. Execute some tools
4. Check web viewer: `http://localhost:37777`
5. Verify observations appear in database
## Troubleshooting
See [README.md](README.md#troubleshooting) for detailed troubleshooting steps.

168
.agent/services/claude-mem/cursor-hooks/PARITY.md Normal file
View File

@@ -0,0 +1,168 @@
# Feature Parity: Claude-Mem Hooks vs Cursor Hooks
This document compares claude-mem's Claude Code hooks with the Cursor hooks implementation to ensure feature parity.
## Hook Mapping
| Claude Code Hook | Cursor Hook | Status | Notes |
|-----------------|-------------|--------|-------|
| `SessionStart` → `context-hook.js` | `beforeSubmitPrompt` → `context-inject.sh` | ✅ Partial | Context fetched but not injectable in Cursor |
| `SessionStart` → `user-message-hook.js` | (Optional) `user-message.sh` | ⚠️ Optional | No SessionStart equivalent; can run on beforeSubmitPrompt |
| `UserPromptSubmit` → `new-hook.js` | `beforeSubmitPrompt` → `session-init.sh` | ✅ Complete | Session init, privacy checks, slash stripping |
| `PostToolUse` → `save-hook.js` | `afterMCPExecution` + `afterShellExecution` → `save-observation.sh` | ✅ Complete | Tool observation capture |
| `PostToolUse` → (file edits) | `afterFileEdit` → `save-file-edit.sh` | ✅ Complete | File edit observation capture |
| `Stop` → `summary-hook.js` | `stop` → `session-summary.sh` | ⚠️ Partial | Summary generation (no transcript access) |
## Feature Comparison
### 1. Session Initialization (`new-hook.js` ↔ `session-init.sh`)
| Feature | Claude Code | Cursor | Status |
|---------|-------------|--------|--------|
| Worker health check | ✅ 75 retries (15s) | ✅ 75 retries (15s) | ✅ Match |
| Session init API call | ✅ `/api/sessions/init` | ✅ `/api/sessions/init` | ✅ Match |
| Privacy check handling | ✅ Checks `skipped` + `reason` | ✅ Checks `skipped` + `reason` | ✅ Match |
| Slash stripping | ✅ Strips leading `/` | ✅ Strips leading `/` | ✅ Match |
| SDK agent init | ✅ `/sessions/{id}/init` | ❌ Not needed | ✅ N/A (Cursor-specific) |
**Status**: ✅ Complete parity (SDK agent init not applicable to Cursor)
### 2. Context Injection (`context-hook.js` ↔ `context-inject.sh`)
| Feature | Claude Code | Cursor | Status |
|---------|-------------|--------|--------|
| Worker health check | ✅ 75 retries | ✅ 75 retries | ✅ Match |
| Context fetch | ✅ `/api/context/inject` | ✅ `/api/context/inject` | ✅ Match |
| Output format | ✅ JSON with `hookSpecificOutput` | ✅ Write to `.cursor/rules/` file | ✅ Alternative |
| Project name extraction | ✅ `getProjectName(cwd)` | ✅ `basename(workspace_root)` | ✅ Match |
| Auto-refresh | ✅ Each session start | ✅ Each prompt submission | ✅ Enhanced |
**Status**: ✅ Complete parity via auto-updated rules file
**How it works**:
- Hook writes context to `.cursor/rules/claude-mem-context.mdc`
- File has `alwaysApply: true` frontmatter
- Cursor auto-includes this rule in all chat sessions
- Context refreshes on every prompt submission
### 3. User Message Display (`user-message-hook.js` ↔ `user-message.sh`)
| Feature | Claude Code | Cursor | Status |
|---------|-------------|--------|--------|
| Context fetch with colors | ✅ `/api/context/inject?colors=true` | ✅ `/api/context/inject?colors=true` | ✅ Match |
| Output channel | ✅ stderr | ✅ stderr | ✅ Match |
| Display format | ✅ Formatted with emojis | ✅ Formatted with emojis | ✅ Match |
| Hook trigger | ✅ SessionStart | ⚠️ Optional (no SessionStart) | ⚠️ Cursor limitation |
**Status**: ⚠️ Optional (no SessionStart equivalent in Cursor)
**Note**: Can be added to `beforeSubmitPrompt` if desired, but may be verbose.
### 4. Observation Capture (`save-hook.js` ↔ `save-observation.sh`)
| Feature | Claude Code | Cursor | Status |
|---------|-------------|--------|--------|
| Worker health check | ✅ 75 retries | ✅ 75 retries | ✅ Match |
| Tool name extraction | ✅ From `tool_name` | ✅ From `tool_name` or "Bash" | ✅ Match |
| Tool input capture | ✅ Full JSON | ✅ Full JSON | ✅ Match |
| Tool response capture | ✅ Full JSON | ✅ Full JSON or output | ✅ Match |
| Privacy tag stripping | ✅ Worker handles | ✅ Worker handles | ✅ Match |
| Error handling | ✅ Fire-and-forget | ✅ Fire-and-forget | ✅ Match |
| Shell command mapping | ✅ N/A (separate hook) | ✅ Maps to "Bash" tool | ✅ Enhanced |
**Status**: ✅ Complete parity (enhanced with shell command support)
### 5. File Edit Capture (N/A ↔ `save-file-edit.sh`)
| Feature | Claude Code | Cursor | Status |
|---------|-------------|--------|--------|
| File path extraction | N/A | ✅ From `file_path` | ✅ New |
| Edit details | N/A | ✅ From `edits` array | ✅ New |
| Tool name | N/A | ✅ "write_file" | ✅ New |
| Edit summary | N/A | ✅ Generated from edits | ✅ New |
**Status**: ✅ New feature (Cursor-specific, not in Claude Code)
### 6. Session Summary (`summary-hook.js` ↔ `session-summary.sh`)
| Feature | Claude Code | Cursor | Status |
|---------|-------------|--------|--------|
| Worker health check | ✅ 75 retries | ✅ 75 retries | ✅ Match |
| Transcript parsing | ✅ Extracts last messages | ❌ No transcript access | ⚠️ Cursor limitation |
| Summary API call | ✅ `/api/sessions/summarize` | ✅ `/api/sessions/summarize` | ✅ Match |
| Last message extraction | ✅ From transcript | ❌ Empty strings | ⚠️ Cursor limitation |
| Error handling | ✅ Fire-and-forget | ✅ Fire-and-forget | ✅ Match |
**Status**: ⚠️ Partial parity (no transcript access in Cursor)
**Note**: Summary generation still works but may be less accurate without last messages. Worker generates summary from observations stored during session.
## Implementation Details
### Worker Health Checks
- **Claude Code**: 75 retries × 200ms = 15 seconds
- **Cursor**: 75 retries × 200ms = 15 seconds
- **Status**: ✅ Match
### Error Handling
- **Claude Code**: Fire-and-forget with logging
- **Cursor**: Fire-and-forget with graceful exit (exit 0)
- **Status**: ✅ Match (adapted for Cursor's hook system)
### Privacy Handling
- **Claude Code**: Worker performs privacy checks, hooks respect `skipped` flag
- **Cursor**: Worker performs privacy checks, hooks respect `skipped` flag
- **Status**: ✅ Match
### Tag Stripping
- **Claude Code**: Worker handles `<private>` and `<claude-mem-context>` tags
- **Cursor**: Worker handles tags (hooks don't need to strip)
- **Status**: ✅ Match
## Missing Features (Cursor Limitations)
1. ~~**Direct Context Injection**~~: **SOLVED** via auto-updated rules file
- Hook writes context to `.cursor/rules/claude-mem-context.mdc`
- Cursor auto-includes rules with `alwaysApply: true`
- Context refreshes on every prompt
2. **Transcript Access**: Cursor hooks don't provide transcript paths
- **Impact**: Summary generation less accurate
- **Workaround**: Worker generates from observations
3. **SessionStart Hook**: Cursor doesn't have session start event
- **Impact**: User message display must be optional
- **Workaround**: Can run on `beforeSubmitPrompt` if desired
4. **SDK Agent Session**: Cursor doesn't use SDK agent pattern
- **Impact**: No `/sessions/{id}/init` call needed
- **Status**: ✅ Not applicable (Cursor-specific)
## Enhancements (Cursor-Specific)
1. **Shell Command Capture**: Maps shell commands to "Bash" tool observations
- **Status**: ✅ Enhanced beyond Claude Code
2. **File Edit Capture**: Dedicated hook for file edits
- **Status**: ✅ New feature
3. **MCP Tool Capture**: Captures MCP tool usage separately
- **Status**: ✅ Enhanced beyond Claude Code
## Summary
| Category | Status |
|----------|--------|
| Core Functionality | ✅ Complete parity |
| Session Management | ✅ Complete parity |
| Observation Capture | ✅ Complete parity (enhanced) |
| Context Injection | ✅ Complete parity (via rules file) |
| Summary Generation | ⚠️ Partial (no transcript) |
| User Experience | ⚠️ Partial (no SessionStart) |
**Overall**: The Cursor hooks implementation achieves **full functional parity** with claude-mem's Claude Code hooks:
- ✅ Session initialization
- ✅ Context injection (via auto-updated `.cursor/rules/` file)
- ✅ Observation capture (MCP tools, shell commands, file edits)
- ⚠️ Summary generation (works, but no transcript access)

112
.agent/services/claude-mem/cursor-hooks/QUICKSTART.md Normal file
View File

@@ -0,0 +1,112 @@
# Quick Start: Claude-Mem + Cursor Integration
> **Give your Cursor AI persistent memory in under 5 minutes**
## What This Does
Connects claude-mem to Cursor so that:
- **Agent actions** (MCP tools, shell commands, file edits) are automatically saved
- **Context from past sessions** is automatically injected via `.cursor/rules/`
- **Sessions are summarized** for future reference
Your AI stops forgetting. It remembers the patterns, decisions, and context from previous sessions.
## Don't Have Claude Code?
If you're using Cursor without Claude Code, see [STANDALONE-SETUP.md](STANDALONE-SETUP.md) for setup with free-tier providers like Gemini or OpenRouter.
---
## Installation (1 minute)
```bash
# Install globally for all projects (recommended)
claude-mem cursor install user
# Or install for current project only
claude-mem cursor install
# Check installation status
claude-mem cursor status
```
## Configure Provider (Required for Standalone)
If you don't have Claude Code, configure a provider for AI summarization:
```bash
# Option A: Gemini (free tier available - recommended)
claude-mem settings set CLAUDE_MEM_PROVIDER gemini
claude-mem settings set CLAUDE_MEM_GEMINI_API_KEY your-api-key
# Option B: OpenRouter (free models available)
claude-mem settings set CLAUDE_MEM_PROVIDER openrouter
claude-mem settings set CLAUDE_MEM_OPENROUTER_API_KEY your-api-key
```
**Get free API keys**:
- Gemini: https://aistudio.google.com/apikey
- OpenRouter: https://openrouter.ai/keys
## Start Worker
```bash
claude-mem start
# Verify it's running
claude-mem status
```
## Restart Cursor
Restart Cursor to load the hooks.
## Verify It's Working
1. Open Cursor Settings → Hooks tab
2. You should see the hooks listed
3. Submit a prompt in Cursor
4. Check the web viewer: http://localhost:37777
5. You should see observations appearing
## What Gets Captured
- **MCP Tool Usage**: All MCP tool executions
- **Shell Commands**: All terminal commands
- **File Edits**: All file modifications
- **Sessions**: Each conversation is tracked
## Accessing Memory
### Via Web Viewer
- Open http://localhost:37777
- Browse sessions, observations, and summaries
- Search your project history
### Via MCP Tools (if enabled)
- claude-mem provides search tools via MCP
- Use `search`, `timeline`, and `get_observations` tools
## Troubleshooting
**Hooks not running?**
- Check Cursor Settings → Hooks tab for errors
- Verify scripts are executable: `chmod +x ~/.cursor/hooks/*.sh`
- Check Hooks output channel in Cursor
**Worker not responding?**
- Check if worker is running: `curl http://127.0.0.1:37777/api/readiness`
- Check logs: `tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log`
- Restart worker: `bun run worker:restart`
**Observations not saving?**
- Check worker logs for errors
- Verify session was initialized in web viewer
- Test API directly: `curl -X POST http://127.0.0.1:37777/api/sessions/observations ...`
## Next Steps
- Read [README.md](README.md) for detailed documentation
- Read [INTEGRATION.md](INTEGRATION.md) for architecture details
- Visit [claude-mem docs](https://docs.claude-mem.ai) for full feature set

246
.agent/services/claude-mem/cursor-hooks/README.md Normal file
View File

@@ -0,0 +1,246 @@
# Claude-Mem Cursor Hooks Integration
> **Persistent AI Memory for Cursor - Free Options Available**
Give your Cursor AI persistent memory across sessions. Your agent remembers what it worked on, the decisions it made, and the patterns in your codebase - automatically.
### Why Claude-Mem?
- **Remember context across sessions**: No more re-explaining your codebase every time
- **Automatic capture**: MCP tools, shell commands, and file edits are logged without effort
- **Free tier options**: Works with Gemini (1500 free req/day) or OpenRouter (free models available)
- **Works with or without Claude Code**: Full functionality either way
### Quick Install (5 minutes)
```bash
# Clone and build
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem && bun install && bun run build
# Interactive setup (configures provider + installs hooks)
bun run cursor:setup
```
---
## Quick Start for Cursor Users
**Using Claude Code?** Skip to [Installation](#installation) - everything works automatically.
**Cursor-only (no Claude Code)?** See [STANDALONE-SETUP.md](STANDALONE-SETUP.md) for free-tier options using Gemini or OpenRouter.
---
## Overview
The hooks bridge Cursor's hook system to claude-mem's worker API, allowing:
- **Session Management**: Initialize sessions and generate summaries
- **Observation Capture**: Record MCP tool usage, shell commands, and file edits
- **Worker Readiness**: Ensure the worker is running before prompt submission
## Context Injection
Context is automatically injected via Cursor's **Rules** system:
1. **Install**: `claude-mem cursor install` generates initial context
2. **Stop hook**: Updates context in `.cursor/rules/claude-mem-context.mdc` after each session
3. **Cursor**: Automatically includes this rule in ALL chat sessions
**The context updates after each session ends**, so the next session sees fresh context.
### Additional Access Methods
- **MCP Tools**: Configure claude-mem's MCP server for `search`, `timeline`, `get_observations` tools
- **Web Viewer**: Access context at `http://localhost:37777`
- **Manual Request**: Ask the agent to search memory
See [CONTEXT-INJECTION.md](CONTEXT-INJECTION.md) for details.
## Installation
### Quick Install (Recommended)
```bash
# Install globally for all projects (recommended)
claude-mem cursor install user
# Or install for current project only
claude-mem cursor install
```
### Manual Installation
<details>
<summary>Click to expand manual installation steps</summary>
**User-level** (recommended - applies to all projects):
```bash
# Copy hooks.json to your home directory
cp cursor-hooks/hooks.json ~/.cursor/hooks.json
# Copy hook scripts
mkdir -p ~/.cursor/hooks
cp cursor-hooks/*.sh ~/.cursor/hooks/
chmod +x ~/.cursor/hooks/*.sh
```
**Project-level** (for per-project hooks):
```bash
# Copy hooks.json to your project
mkdir -p .cursor
cp cursor-hooks/hooks.json .cursor/hooks.json
# Copy hook scripts to your project
mkdir -p .cursor/hooks
cp cursor-hooks/*.sh .cursor/hooks/
chmod +x .cursor/hooks/*.sh
```
</details>
### After Installation
1. **Start the worker**:
```bash
claude-mem start
```
2. **Restart Cursor** to load the hooks
3. **Verify installation**:
```bash
claude-mem cursor status
```
## Hook Mappings
| Cursor Hook | Script | Purpose |
|-------------|--------|---------|
| `beforeSubmitPrompt` | `session-init.sh` | Initialize claude-mem session |
| `beforeSubmitPrompt` | `context-inject.sh` | Ensure worker is running |
| `afterMCPExecution` | `save-observation.sh` | Capture MCP tool usage |
| `afterShellExecution` | `save-observation.sh` | Capture shell command execution |
| `afterFileEdit` | `save-file-edit.sh` | Capture file edits |
| `stop` | `session-summary.sh` | Generate summary + update context file |
## How It Works
### Session Initialization (`session-init.sh`)
- Called before each prompt submission
- Initializes a new session in claude-mem using `conversation_id` as the session ID
- Extracts project name from workspace root
- Outputs `{"continue": true}` to allow prompt submission
### Context Hook (`context-inject.sh`)
- Ensures claude-mem worker is running before session
- Outputs `{"continue": true}` to allow prompt submission
- Note: Context file is updated by `session-summary.sh` (stop hook), not here
### Observation Capture (`save-observation.sh`)
- Captures MCP tool executions and shell commands
- Maps them to claude-mem's observation format
- Sends to `/api/sessions/observations` endpoint (fire-and-forget)
### File Edit Capture (`save-file-edit.sh`)
- Captures file edits made by the agent
- Treats edits as "write_file" tool usage
- Includes edit summaries in observations
### Session Summary (`session-summary.sh`)
- Called when agent loop ends (stop hook)
- Requests summary generation from claude-mem
- **Updates context file** in `.cursor/rules/claude-mem-context.mdc` for next session
## Configuration
The hooks read configuration from `~/.claude-mem/settings.json`:
- `CLAUDE_MEM_WORKER_PORT`: Worker port (default: 37777)
- `CLAUDE_MEM_WORKER_HOST`: Worker host (default: 127.0.0.1)
## Dependencies
The hook scripts require:
- `jq` - JSON processing
- `curl` - HTTP requests
- `bash` - Shell interpreter
Install on macOS: `brew install jq curl`
Install on Ubuntu: `apt-get install jq curl`
## Troubleshooting
### Hooks not executing
1. Check hooks are in the correct location:
```bash
ls .cursor/hooks.json # Project-level
ls ~/.cursor/hooks.json # User-level
```
2. Verify scripts are executable:
```bash
chmod +x ~/.cursor/hooks/*.sh
```
3. Check Cursor Settings → Hooks tab for configuration status
4. Check Hooks output channel in Cursor for error messages
### Worker not responding
1. Verify worker is running:
```bash
curl http://127.0.0.1:37777/api/readiness
```
2. Check worker logs:
```bash
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
```
3. Restart worker:
```bash
claude-mem restart
```
### Observations not being saved
1. Monitor worker logs for incoming requests
2. Verify session was initialized via web viewer at `http://localhost:37777`
3. Test observation endpoint directly:
```bash
curl -X POST http://127.0.0.1:37777/api/sessions/observations \
-H "Content-Type: application/json" \
-d '{"contentSessionId":"test","tool_name":"test","tool_input":{},"tool_response":{},"cwd":"/tmp"}'
```
## Comparison with Claude Code Integration
| Feature | Claude Code | Cursor |
|---------|-------------|--------|
| Session Initialization | ✅ `SessionStart` hook | ✅ `beforeSubmitPrompt` hook |
| Context Injection | ✅ `additionalContext` field | ✅ Auto-updated `.cursor/rules/` file |
| Observation Capture | ✅ `PostToolUse` hook | ✅ `afterMCPExecution`, `afterShellExecution`, `afterFileEdit` |
| Session Summary | ✅ `Stop` hook with transcript | ⚠️ `stop` hook (no transcript) |
| MCP Search Tools | ✅ Full support | ✅ Full support (if MCP configured) |
## Files
- `hooks.json` - Hook configuration
- `common.sh` - Shared utility functions
- `session-init.sh` - Session initialization
- `context-inject.sh` - Context/worker readiness hook
- `save-observation.sh` - MCP and shell observation capture
- `save-file-edit.sh` - File edit observation capture
- `session-summary.sh` - Summary generation
- `cursorrules-template.md` - Template for `.cursorrules` file
## See Also
- [Claude-Mem Documentation](https://docs.claude-mem.ai)
- [Cursor Hooks Reference](../docs/context/cursor-hooks-reference.md)
- [Claude-Mem Architecture](https://docs.claude-mem.ai/architecture/overview)

327
.agent/services/claude-mem/cursor-hooks/REVIEW.md Normal file
View File

@@ -0,0 +1,327 @@
# Comprehensive Review: Cursor Hooks Integration
## Overview
This document provides a thorough review of the Cursor hooks integration, covering all aspects from implementation details to edge cases and potential issues.
## Architecture Review
### ✅ Strengths
1. **Modular Design**: Common utilities extracted to `common.sh` for reusability
2. **Error Handling**: Graceful degradation - hooks never block Cursor even on failures
3. **Parity with Claude Code**: Matches claude-mem's hook behavior where possible
4. **Fire-and-Forget**: Observations sent asynchronously, don't block agent execution
### ⚠️ Limitations (Platform-Specific)
1. **No Windows Support**: Bash scripts require Unix-like environment
- **Mitigation**: Could add PowerShell equivalents or use Node.js/Python wrappers
2. **Dependency on jq/curl**: Requires external tools
- **Mitigation**: Dependency checks added, graceful fallback
## Script-by-Script Review
### 1. `common.sh` - Utility Functions
**Purpose**: Shared utilities for all hook scripts
**Functions**:
- ✅ `check_dependencies()` - Validates jq and curl exist
- ✅ `read_json_input()` - Safely reads and validates JSON from stdin
- ✅ `get_worker_port()` - Reads port from settings with validation
- ✅ `ensure_worker_running()` - Health checks with retries
- ✅ `url_encode()` - URL encoding for special characters
- ✅ `get_project_name()` - Extracts project name with edge case handling
- ✅ `json_get()` - Safe JSON field extraction with array support
- ✅ `is_empty()` - Null/empty string detection
**Edge Cases Handled**:
- ✅ Empty stdin
- ✅ Malformed JSON
- ✅ Missing settings file
- ✅ Invalid port numbers
- ✅ Windows drive roots (C:\, etc.)
- ✅ Empty workspace roots
- ✅ Array field access (`workspace_roots[0]`)
**Potential Issues**:
- ⚠️ `url_encode()` uses jq - if jq fails, encoding fails silently
- ✅ **Fixed**: Falls back to original string if encoding fails
### 2. `session-init.sh` - Session Initialization
**Purpose**: Initialize claude-mem session when prompt is submitted
**Flow**:
1. Read and validate JSON input
2. Extract session_id, project, prompt
3. Ensure worker is running
4. Strip leading slash from prompt (parity with new-hook.ts)
5. Call `/api/sessions/init`
6. Handle privacy checks
**Edge Cases Handled**:
- ✅ Empty conversation_id → fallback to generation_id
- ✅ Empty workspace_root → fallback to pwd
- ✅ Empty prompt → still initializes session
- ✅ Worker unavailable → graceful exit
- ✅ Privacy-skipped sessions → silent exit
- ✅ Invalid JSON → graceful exit
**Potential Issues**:
- ✅ **Fixed**: String slicing now checks for empty strings
- ✅ **Fixed**: All jq operations have error handling
- ✅ **Fixed**: Worker health check with proper retries
**Parity with Claude Code**:
- ✅ Session initialization
- ✅ Privacy check handling
- ✅ Slash stripping
- ❌ SDK agent init (not applicable to Cursor)
### 3. `save-observation.sh` - Observation Capture
**Purpose**: Capture MCP tool usage and shell commands
**Flow**:
1. Read and validate JSON input
2. Determine hook type (MCP vs Shell)
3. Extract tool data
4. Validate JSON structures
5. Ensure worker is running
6. Send observation (fire-and-forget)
**Edge Cases Handled**:
- ✅ Empty tool_name → exit gracefully
- ✅ Invalid tool_input/tool_response → default to {}
- ✅ Malformed JSON in tool data → validated and sanitized
- ✅ Empty session_id → exit gracefully
- ✅ Worker unavailable → exit gracefully
**Potential Issues**:
- ✅ **Fixed**: JSON validation for tool_input and tool_response
- ✅ **Fixed**: Proper handling of empty/null values
- ✅ **Fixed**: Error handling for all jq operations
**Parity with Claude Code**:
- ✅ Tool observation capture
- ✅ Privacy tag stripping (handled by worker)
- ✅ Fire-and-forget pattern
- ✅ Enhanced: Shell command capture (not in Claude Code)
### 4. `save-file-edit.sh` - File Edit Capture
**Purpose**: Capture file edits as observations
**Flow**:
1. Read and validate JSON input
2. Extract file_path and edits array
3. Validate edits array
4. Create edit summary
5. Ensure worker is running
6. Send observation (fire-and-forget)
**Edge Cases Handled**:
- ✅ Empty file_path → exit gracefully
- ✅ Empty edits array → exit gracefully
- ✅ Invalid edits JSON → default to []
- ✅ Malformed edit objects → summary generation handles gracefully
- ✅ Empty session_id → exit gracefully
**Potential Issues**:
- ✅ **Fixed**: Edit summary generation with error handling
- ✅ **Fixed**: Array validation before processing
- ✅ **Fixed**: Safe string slicing in summary generation
**Parity with Claude Code**:
- ✅ File edit capture (new feature for Cursor)
- ✅ Observation format matches claude-mem structure
### 5. `session-summary.sh` - Summary Generation
**Purpose**: Generate session summary when agent loop ends
**Flow**:
1. Read and validate JSON input
2. Extract session_id
3. Ensure worker is running
4. Send summarize request with empty messages (no transcript access)
5. Output empty JSON (required by Cursor)
**Edge Cases Handled**:
- ✅ Empty session_id → exit gracefully
- ✅ Worker unavailable → exit gracefully
- ✅ Missing transcript → empty messages (worker handles gracefully)
**Potential Issues**:
- ✅ **Fixed**: Proper JSON output for Cursor stop hook
- ✅ **Fixed**: Worker handles empty messages (verified in codebase)
**Parity with Claude Code**:
- ⚠️ Partial: No transcript access, so no last_user_message/last_assistant_message
- ✅ Summary generation still works (based on observations)
### 6. `context-inject.sh` - Context Injection via Rules File
**Purpose**: Fetch context and write to `.cursor/rules/` for auto-injection
**How It Works**:
1. Fetches context from claude-mem worker
2. Writes to `.cursor/rules/claude-mem-context.mdc` with `alwaysApply: true`
3. Cursor auto-includes this rule in all chat sessions
4. Context refreshes on every prompt submission
**Flow**:
1. Read and validate JSON input
2. Extract workspace root
3. Get project name
4. Ensure worker is running
5. Fetch context from `/api/context/inject`
6. Write context to `.cursor/rules/claude-mem-context.mdc`
7. Output `{"continue": true}`
**Edge Cases Handled**:
- ✅ Empty workspace_root → fallback to pwd
- ✅ Worker unavailable → allow prompt to continue
- ✅ Context fetch failure → allow prompt to continue (no file written)
- ✅ Special characters in project name → URL encoded
- ✅ Missing `.cursor/rules/` directory → created automatically
**Parity with Claude Code**:
- ✅ Context injection achieved via rules file workaround
- ✅ Worker readiness check matches Claude Code
- ✅ Context available immediately in next prompt
## Error Handling Review
### ✅ Comprehensive Error Handling
1. **Input Validation**:
- ✅ Empty stdin → default to `{}`
- ✅ Malformed JSON → validated and sanitized
- ✅ Missing fields → safe fallbacks
2. **Dependency Checks**:
- ✅ jq and curl existence checked
- ✅ Non-blocking (warns but continues)
3. **Network Errors**:
- ✅ Worker unavailable → graceful exit
- ✅ HTTP failures → fire-and-forget (don't block)
- ✅ Timeout handling → 15 second retries
4. **Data Validation**:
- ✅ Port number validation (1-65535)
- ✅ JSON structure validation
- ✅ Empty/null value handling
## Security Review
### ✅ Security Considerations
1. **Input Sanitization**:
- ✅ JSON validation prevents injection
- ✅ URL encoding for special characters
- ✅ Worker handles privacy tag stripping
2. **Error Information**:
- ✅ Errors don't expose sensitive data
- ✅ Fire-and-forget prevents information leakage
3. **Dependency Security**:
- ✅ Uses standard tools (jq, curl)
- ✅ No custom code execution
## Performance Review
### ✅ Performance Optimizations
1. **Non-Blocking**:
- ✅ All hooks exit quickly (don't block Cursor)
- ✅ Observations sent asynchronously
2. **Efficient Health Checks**:
- ✅ 200ms polling interval
- ✅ 15 second maximum wait
- ✅ Early exit on success
3. **Resource Usage**:
- ✅ Minimal memory footprint
- ✅ No long-running processes
- ✅ Fire-and-forget HTTP requests
## Testing Recommendations
### Unit Tests Needed
1. **common.sh functions**:
- [ ] Test `json_get()` with various field types
- [ ] Test `get_project_name()` with edge cases
- [ ] Test `url_encode()` with special characters
- [ ] Test `ensure_worker_running()` with various states
2. **Hook scripts**:
- [ ] Test with empty input
- [ ] Test with malformed JSON
- [ ] Test with missing fields
- [ ] Test with worker unavailable
- [ ] Test with invalid port numbers
### Integration Tests Needed
1. **End-to-end flow**:
- [ ] Session initialization → observation capture → summary
- [ ] Multiple concurrent hooks
- [ ] Worker restart scenarios
2. **Edge cases**:
- [ ] Very long prompts/commands
- [ ] Special characters in paths
- [ ] Unicode in tool inputs
- [ ] Large file edits
## Known Limitations
1. **Cursor Hook System**:
- ✅ Context injection solved via `.cursor/rules/` file
- ❌ No transcript access for summary generation
- ❌ No SessionStart equivalent
2. **Platform Support**:
- ⚠️ Bash scripts (Unix-like only)
- ⚠️ Requires jq and curl
3. **Context Injection**:
- ✅ Solved via auto-updated `.cursor/rules/claude-mem-context.mdc`
- ✅ Context also available via MCP tools
- ✅ Context also available via web viewer
## Recommendations
### Immediate Improvements
1. ✅ **DONE**: Comprehensive error handling
2. ✅ **DONE**: Input validation
3. ✅ **DONE**: Dependency checks
4. ✅ **DONE**: URL encoding
### Future Enhancements
1. **Logging**: Add optional debug logging to help troubleshoot
2. **Metrics**: Track hook execution times and success rates
3. **Windows Support**: PowerShell or Node.js equivalents
4. **Testing**: Automated test suite
5. **Documentation**: More examples and troubleshooting guides
## Conclusion
The Cursor hooks integration is **production-ready** with:
- ✅ Comprehensive error handling
- ✅ Input validation and sanitization
- ✅ Graceful degradation
- ✅ Feature parity with Claude Code hooks (where applicable)
- ✅ Enhanced features (shell/file edit capture)
The implementation handles edge cases well and follows best practices for reliability and maintainability.

293
.agent/services/claude-mem/cursor-hooks/STANDALONE-SETUP.md Normal file
View File

@@ -0,0 +1,293 @@
# Claude-Mem for Cursor (No Claude Code Required)
> **Persistent AI Memory for Cursor - Zero Cost to Start**
## Overview
Use claude-mem's persistent memory in Cursor without a Claude Code subscription. Choose between free-tier providers (Gemini, OpenRouter) or paid options.
**What You Get**:
- **Persistent memory** that survives across sessions - your AI remembers what it worked on
- **Automatic capture** of MCP tools, shell commands, and file edits
- **Context injection** via `.cursor/rules/` - relevant history included in every chat
- **Web viewer** at http://localhost:37777 - browse and search your project history
**Why This Matters**: Every Cursor session starts fresh. Claude-mem bridges that gap - your AI agent builds cumulative knowledge about your codebase, decisions, and patterns over time.
## Prerequisites
### macOS / Linux
- Cursor IDE
- [Bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`)
- Git
- `jq` and `curl`:
- **macOS**: `brew install jq curl`
- **Linux**: `apt install jq curl`
### Windows
- Cursor IDE
- [Bun](https://bun.sh) (PowerShell: `powershell -c "irm bun.sh/install.ps1 | iex"`)
- Git
- PowerShell 5.1+ (included with Windows 10/11)
## Step 1: Clone Claude-Mem
```bash
# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# Install dependencies
bun install
# Build the project
bun run build
```
## Step 2: Configure Provider (Choose One)
Since you don't have Claude Code, you need to configure an AI provider for claude-mem's summarization engine.
### Option A: Gemini (Recommended - Free Tier)
Gemini offers 1500 free requests per day, plenty for typical usage.
```bash
# Create settings directory
mkdir -p ~/.claude-mem
# Create settings file
cat > ~/.claude-mem/settings.json << 'EOF'
{
"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY",
"CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash-lite",
"CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED": true
}
EOF
```
**Get your free API key**: https://aistudio.google.com/apikey
### Option B: OpenRouter (100+ Models)
OpenRouter provides access to many models, including free options.
```bash
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
"CLAUDE_MEM_PROVIDER": "openrouter",
"CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
}
EOF
```
**Get your API key**: https://openrouter.ai/keys
**Free models available**:
- `google/gemini-2.0-flash-exp:free`
- `xiaomi/mimo-v2-flash:free`
### Option C: Claude API (If You Have API Access)
If you have Anthropic API credits but not a Claude Code subscription:
```bash
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
"CLAUDE_MEM_PROVIDER": "claude",
"ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY"
}
EOF
```
## Step 3: Install Cursor Hooks
```bash
# From the claude-mem repo directory (recommended - all projects)
bun run cursor:install -- user
# Or for project-level only:
bun run cursor:install
```
This installs:
- Hook scripts to `.cursor/hooks/`
- Hook configuration to `.cursor/hooks.json`
- Context template to `.cursor/rules/`
## Step 4: Start the Worker
```bash
bun run worker:start
```
The worker runs in the background and handles:
- Session management
- Observation processing
- AI-powered summarization
- Context file updates
## Step 5: Restart Cursor & Verify
1. **Restart Cursor IDE** to load the new hooks
2. **Check installation status**:
```bash
bun run cursor:status
```
3. **Verify the worker is running**:
```bash
curl http://127.0.0.1:37777/api/readiness
```
Should return: `{"status":"ready"}`
4. **Open the web viewer**: http://localhost:37777
## How It Works
1. **Before each prompt**: Hooks initialize a session and ensure the worker is running
2. **During agent work**: MCP tools, shell commands, and file edits are captured
3. **When agent stops**: Summary is generated and context file is updated
4. **Next session**: Fresh context is automatically injected via `.cursor/rules/`
## Troubleshooting
### "No provider configured" error
Verify your settings file exists and has valid credentials:
```bash
cat ~/.claude-mem/settings.json
```
### Worker not starting
Check logs:
```bash
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
```
### Hooks not executing
1. Check Cursor Settings → Hooks tab for errors
2. Verify scripts are executable:
```bash
chmod +x ~/.cursor/hooks/*.sh
```
3. Check the Hooks output channel in Cursor
### Rate limiting (Gemini free tier)
If you hit the 1500 requests/day limit:
- Wait until the next day
- Upgrade to a paid plan
- Switch to OpenRouter with a paid model
## Next Steps
- Read [README.md](README.md) for detailed hook documentation
- Check [CONTEXT-INJECTION.md](CONTEXT-INJECTION.md) for context behavior details
- Visit https://docs.claude-mem.ai for full documentation
## Quick Reference
| Command | Purpose |
|---------|---------|
| `bun run cursor:install -- user` | Install hooks for all projects (recommended) |
| `bun run cursor:install` | Install hooks for current project only |
| `bun run cursor:status` | Check installation status |
| `bun run worker:start` | Start the background worker |
| `bun run worker:stop` | Stop the background worker |
| `bun run worker:restart` | Restart the worker |
---
## Windows Installation
Windows users get full support via PowerShell scripts. The installer automatically detects Windows and installs the appropriate scripts.
### Enable Script Execution (if needed)
PowerShell may require you to enable script execution:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
### Step-by-Step for Windows
```powershell
# Clone and build
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
bun install
bun run build
# Configure provider (Gemini example)
$settingsDir = "$env:USERPROFILE\.claude-mem"
New-Item -ItemType Directory -Force -Path $settingsDir
@"
{
"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
"@ | Out-File -FilePath "$settingsDir\settings.json" -Encoding UTF8
# Interactive setup (recommended - walks you through everything)
bun run cursor:setup
# Or manual installation
bun run cursor:install
bun run worker:start
```
### What Gets Installed on Windows
The installer copies these PowerShell scripts to `.cursor\hooks\`:
| Script | Purpose |
|--------|---------|
| `common.ps1` | Shared utilities |
| `session-init.ps1` | Initialize session on prompt |
| `context-inject.ps1` | Inject memory context |
| `save-observation.ps1` | Capture MCP/shell usage |
| `save-file-edit.ps1` | Capture file edits |
| `session-summary.ps1` | Generate summary on stop |
The `hooks.json` file is configured to invoke PowerShell with `-ExecutionPolicy Bypass` to ensure scripts run without additional configuration.
### Windows Troubleshooting
**"Execution of scripts is disabled on this system"**
Run as Administrator:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
```
**PowerShell scripts not running**
Verify the hooks.json contains PowerShell invocations:
```powershell
Get-Content .cursor\hooks.json
```
Should show commands like:
```
powershell.exe -ExecutionPolicy Bypass -File "./.cursor/hooks/session-init.ps1"
```
**Worker not responding**
Check if port 37777 is in use:
```powershell
Get-NetTCPConnection -LocalPort 37777
```
**Antivirus blocking scripts**
Some antivirus software may block PowerShell scripts. Add an exception for the `.cursor\hooks\` directory if needed.

84
.agent/services/claude-mem/cursor-hooks/cursorrules-template.md Normal file
View File

@@ -0,0 +1,84 @@
# Claude-Mem Rules for Cursor
## Automatic Context Injection
The `context-inject.sh` hook **automatically creates and updates** a rules file at:
```
.cursor/rules/claude-mem-context.mdc
```
This file:
- Has `alwaysApply: true` so it's included in every chat session
- Contains recent context from past sessions
- Auto-refreshes on every prompt submission
**You don't need to manually create any rules file!**
## Optional: Additional Instructions
If you want to add custom instructions about claude-mem (beyond the auto-injected context), create a separate rules file:
### `.cursor/rules/claude-mem-instructions.mdc`
```markdown
---
alwaysApply: true
description: "Instructions for using claude-mem memory system"
---
# Memory System Usage
You have access to claude-mem, a persistent memory system. In addition to the auto-injected context above, you can search for more detailed information using MCP tools:
## Available MCP Tools
1. **search** - Find relevant past observations
```
search(query="authentication bug", project="my-project", limit=10)
```
2. **timeline** - Get context around a specific observation
```
timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
```
3. **get_observations** - Fetch full details for specific IDs
```
get_observations(ids=[123, 456])
```
## When to Search Memory
- When the user asks about previous work or decisions
- When encountering unfamiliar code patterns in this project
- When debugging issues that might have been addressed before
- When asked to continue or build upon previous work
## 3-Layer Workflow
Follow this pattern for token efficiency:
1. **Search first** - Get compact index (~50-100 tokens/result)
2. **Timeline** - Get chronological context around interesting results
3. **Fetch details** - Only for relevant observations (~500-1000 tokens/result)
Never fetch full details without filtering first.
```
## File Locations
| File | Purpose | Created By |
|------|---------|------------|
| `.cursor/rules/claude-mem-context.mdc` | Auto-injected context | Hook (automatic) |
| `.cursor/rules/claude-mem-instructions.mdc` | MCP tool instructions | You (optional) |
## Git Ignore
If you don't want to commit the auto-generated context file:
```gitignore
# .gitignore
.cursor/rules/claude-mem-context.mdc
```
The instructions file can be committed to share with your team.

34
.agent/services/claude-mem/cursor-hooks/hooks.json Normal file
View File

@@ -0,0 +1,34 @@
{
"version": 1,
"hooks": {
"beforeSubmitPrompt": [
{
"command": "./cursor-hooks/session-init.sh"
},
{
"command": "./cursor-hooks/context-inject.sh"
}
],
"afterMCPExecution": [
{
"command": "./cursor-hooks/save-observation.sh"
}
],
"afterShellExecution": [
{
"command": "./cursor-hooks/save-observation.sh"
}
],
"afterFileEdit": [
{
"command": "./cursor-hooks/save-file-edit.sh"
}
],
"stop": [
{
"command": "./cursor-hooks/session-summary.sh"
}
]
}
}

83
.agent/services/claude-mem/docs/CLAUDE.md Normal file
View File

@@ -0,0 +1,83 @@
<claude-mem-context>
# Recent Activity
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 6, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #4241 | 11:19 PM | 🟣 | Object-Oriented Architecture Design Document Created | ~662 |
| #4240 | 11:11 PM | 🟣 | Worker Service Rewrite Blueprint Created | ~541 |
| #4239 | 11:07 PM | 🟣 | Comprehensive Worker Service Performance Analysis Document Created | ~541 |
| #4238 | 10:59 PM | 🔵 | Overhead Analysis Document Checked | ~203 |
### Nov 7, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #4609 | 6:33 PM | ✅ | PR #69 Successfully Merged to Main Branch | ~516 |
| #4600 | 6:31 PM | 🟣 | Added Worker Service Documentation Suite | ~441 |
| #4597 | " | 🔄 | Worker Service Refactored to Object-Oriented Architecture | ~473 |
### Nov 8, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #5539 | 10:20 PM | 🔵 | Harsh critical audit of context-hook reveals systematic anti-patterns | ~3154 |
| #5497 | 9:29 PM | 🔵 | Harsh critical audit of context-hook reveals systematic anti-patterns | ~2815 |
| #5495 | 9:28 PM | 🔵 | Context Hook Audit Reveals Project Anti-Patterns | ~660 |
| #5476 | 9:17 PM | 🔵 | Critical Code Audit Identified 14 Anti-Patterns in Context Hook | ~887 |
| #5391 | 8:45 PM | 🔵 | Critical Code Quality Audit of Context Hook Implementation | ~720 |
| #5150 | 7:37 PM | 🟣 | Troubleshooting Skill Added to Claude-Mem Plugin | ~427 |
### Nov 9, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #6161 | 11:55 PM | 🔵 | YC W26 Application Research and Preparation Completed for Claude-Mem | ~1628 |
| #6155 | 11:47 PM | ✅ | Comprehensive Y Combinator Winter 2026 Application Notes Created | ~1045 |
| #5979 | 7:58 PM | 🔵 | Smart Contextualization Feature Architecture | ~560 |
| #5971 | 7:49 PM | 🔵 | Hooks Reference Documentation Structure | ~448 |
| #5929 | 7:08 PM | ✅ | Documentation Updates for v5.4.0 Skill-Based Search Migration | ~604 |
| #5927 | " | ✅ | Updated Configuration Documentation for Skill-Based Search | ~497 |
| #5920 | 7:05 PM | ✅ | Renamed Architecture Documentation File Reference | ~271 |
### Nov 18, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11515 | 8:22 PM | 🔵 | Smart Contextualization Architecture Retrieved with Command Hook Pattern Details | ~502 |
### Dec 8, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #22294 | 9:43 PM | 🔵 | Documentation Site Structure Located | ~359 |
### Dec 12, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #24430 | 8:27 PM | ✅ | Removed Final Platform Check Reference from Linux Section | ~320 |
| #24429 | " | ✅ | Final Platform Check Reference Removal from Linux Section | ~274 |
| #24428 | " | ✅ | Corrected Second Line Number Reference for Migration Marker Logic | ~267 |
| #24427 | 8:26 PM | ✅ | Updated Line Number Reference for PM2 Cleanup Implementation | ~260 |
| #24426 | " | ✅ | Removed Platform Check from Manual Marker Deletion Scenario | ~338 |
| #24425 | " | ✅ | Removed Platform Check from Fresh Install Scenario Flow | ~314 |
| #24424 | 8:25 PM | ✅ | Renumbered Manual Marker Deletion Scenario | ~285 |
| #24423 | " | ✅ | Renumbered Fresh Install Scenario | ~243 |
| #24422 | " | ✅ | Removed Obsolete Windows Platform Detection Scenario | ~311 |
| #24421 | " | ✅ | Removed Platform Check from macOS Migration Documentation | ~294 |
| #24420 | 8:24 PM | ✅ | Platform Check Removed from Migration Documentation | ~288 |
| #24417 | 8:16 PM | ✅ | Code Reference Example Updated to Reflect Actual Cross-Platform Implementation | ~366 |
| #24416 | " | ✅ | Architecture Decision Documentation Updated to Reflect Cross-Platform PM2 Cleanup Rationale | ~442 |
| #24415 | 8:15 PM | ✅ | Migration Marker Lifecycle Documentation Updated for Unified Cross-Platform Behavior | ~463 |
| #24414 | " | ✅ | Platform Comparison Table Updated to Reflect Unified Cross-Platform Migration | ~351 |
| #24413 | " | ✅ | Windows Platform-Specific Documentation Completely Rewritten for Unified Migration | ~428 |
| #24412 | " | ✅ | User Experience Timeline Updated for Cross-Platform PM2 Cleanup | ~291 |
| #24411 | 8:14 PM | ✅ | Migration Marker Lifecycle Documentation Updated for All Platforms | ~277 |
| #24410 | " | ✅ | Marker File Platform Behavior Documentation Updated for Unified Migration | ~282 |
| #24409 | " | ✅ | Migration Steps Documentation Updated for Cross-Platform PM2 Cleanup | ~278 |
| #24408 | 8:13 PM | ✅ | PM2 Migration Documentation Updated to Remove Windows Platform Check | ~280 |
</claude-mem-context>

213
.agent/services/claude-mem/docs/PR-SHIPPING-REPORT.md Normal file
View File

@@ -0,0 +1,213 @@
# Claude-Mem PR Shipping Report
*Generated: 2026-02-04*
## Executive Summary
6 PRs analyzed for shipping readiness. **1 is ready to merge**, 4 have conflicts, 1 is too large for easy review.
| PR | Title | Status | Recommendation |
|----|-------|--------|----------------|
| **#856** | Idle timeout for zombie processes | ✅ **MERGEABLE** | **Ship it** |
| #700 | Windows Terminal popup fix | ⚠️ Conflicts | Rebase, then ship |
| #722 | In-process worker architecture | ⚠️ Conflicts | Rebase, high impact |
| #657 | generate/clean CLI commands | ⚠️ Conflicts | Rebase, then ship |
| #863 | Ragtime email investigation | 🔍 Needs review | Research pending |
| #464 | Sleep Agent Pipeline (contributor) | 🔴 Too large | Request split or dedicated review |
---
## Ready to Ship
### PR #856: Idle Timeout for Zombie Observer Processes
**Status:** ✅ MERGEABLE (no conflicts)
| Metric | Value |
|--------|-------|
| Additions | 928 |
| Deletions | 171 |
| Files | 8 |
| Risk | Low-Medium |
**What it does:**
- Adds 3-minute idle timeout to `SessionQueueProcessor`
- Prevents zombie observer processes that were causing 13.4GB swap usage
- Processes exit gracefully after inactivity instead of waiting forever
**Why ship it:**
- Fixes real user-reported issue (79 zombie processes)
- Well-tested (11 new tests, 440 lines of test coverage)
- Clean implementation, preventive approach
- Supersedes PR #848's reactive cleanup
- No conflicts, ready to merge
**Review notes:**
- 1 Greptile bot comment (addressed)
- Race condition fix included
- Enhanced logging added
---
## Needs Rebase (Have Conflicts)
### PR #700: Windows Terminal Popup Fix
**Status:** ⚠️ CONFLICTING
| Metric | Value |
|--------|-------|
| Additions | 187 |
| Deletions | 399 |
| Files | 8 |
| Risk | Medium |
**What it does:**
- Eliminates Windows Terminal popup by removing spawn-based daemon
- Worker `start` command becomes daemon directly (no child spawn)
- Removes `restart` command (users do `stop` then `start`)
- Net simplification: -212 lines
**Breaking changes:**
- `restart` command removed
**Review status:**
- ✅ 1 APPROVAL from @volkanfirat (Jan 15, 2026)
**Action needed:** Resolve conflicts, then ready to ship.
---
### PR #722: In-Process Worker Architecture
**Status:** ⚠️ CONFLICTING
| Metric | Value |
|--------|-------|
| Additions | 869 |
| Deletions | 4,658 |
| Files | 112 |
| Risk | High |
**What it does:**
- Hook processes become the worker (no separate daemon spawning)
- First hook that needs worker becomes the worker
- Eliminates Windows spawn issues ("NO SPAWN" rule)
- 761 tests pass
**Architectural impact:** HIGH
- Fundamentally changes worker lifecycle
- Hook processes stay alive (they ARE the worker)
- First hook wins port 37777, others use HTTP
**Action needed:** Resolve conflicts. Consider relationship with PR #700 (both touch worker architecture).
---
### PR #657: Generate/Clean CLI Commands
**Status:** ⚠️ CONFLICTING
| Metric | Value |
|--------|-------|
| Additions | 1,184 |
| Deletions | 5,057 |
| Files | 104 |
| Risk | Medium |
**What it does:**
- Adds `claude-mem generate` and `claude-mem clean` CLI commands
- Fixes validation bugs (deleted folders recreated from stale DB)
- Fixes Windows path handling
- Adds automatic shell alias installation
- Disables subdirectory CLAUDE.md files by default
**Breaking changes:**
- Default behavior change: folder CLAUDE.md now disabled by default
**Action needed:** Resolve conflicts, complete Windows testing.
---
## Needs Attention
### PR #863: Ragtime Email Investigation
**Status:** 🔍 Research pending
Research agent did not return results. Manual review needed.
---
### PR #464: Sleep Agent Pipeline (Contributor: @laihenyi)
**Status:** 🔴 Too large for effective review
| Metric | Value |
|--------|-------|
| Additions | 15,430 |
| Deletions | 469 |
| Files | 73 |
| Wait time | 37+ days |
| Risk | High |
**What it does:**
- Sleep Agent Pipeline with memory tiering
- Supersession detection
- Session Statistics API (`/api/session/:id/stats`)
- StatusLine + PreCompact hooks
- Context Generator improvements
- Self-healing CI workflow
**Concerns:**
| Issue | Details |
|-------|---------|
| 🔴 Size | 15K+ lines is too large for effective review |
| 🔴 SupersessionDetector | Single file with 1,282 additions |
| 🟡 No tests visible | Test plan checkboxes unchecked |
| 🟡 Self-healing CI | Auto-fix workflow could cause infinite commit loops |
| 🟡 Serena config | Adds `.serena/` tooling |
**Recommendation:**
1. **Option A:** Request contributor split into 4-5 smaller PRs
2. **Option B:** Allocate dedicated review time (several hours)
3. **Option C:** Cherry-pick specific features (hooks, stats API)
**Note:** Contributor has been waiting 37+ days. Deserves response either way.
---
## Shipping Strategy
### Phase 1: Quick Wins (This Week)
1. **Merge #856** — Ready now, fixes real user issue
2. **Rebase #700** — Has approval, Windows fix needed
3. **Rebase #657** — Useful CLI commands
### Phase 2: Architecture (Careful Review)
4. **Review #722** — High impact, conflicts with #700 approach?
- Both PRs eliminate spawning but in different ways
- May need to pick one approach
### Phase 3: Contributor PR
5. **Respond to #464** — Options:
- Ask for split
- Schedule dedicated review
- Cherry-pick subset
### Phase 4: Investigation
6. **Manual review #863** — Ragtime email feature
---
## Conflict Resolution Order
Since multiple PRs have conflicts, suggested rebase order:
1. **#856** (merge first — no conflicts)
2. **#700** (rebase onto main after #856)
3. **#657** (rebase onto main after #700)
4. **#722** (rebase last — may conflict with #700 architecturally)
---
## Summary
| Ready | Conflicts | Needs Work |
|-------|-----------|------------|
| 1 PR (#856) | 3 PRs (#700, #722, #657) | 2 PRs (#464, #863) |
**Immediate action:** Merge #856, then rebase the conflict PRs in order.

239
.agent/services/claude-mem/docs/SESSION_ID_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,239 @@
# Session ID Architecture
## Overview
Claude-mem uses **two distinct session IDs** to track conversations and memory:
1. **`contentSessionId`** - The user's Claude Code conversation session ID
2. **`memorySessionId`** - The SDK agent's internal session ID for resume functionality
## Critical Architecture
### Initialization Flow
```
┌─────────────────────────────────────────────────────────────┐
│ 1. Hook creates session │
│ createSDKSession(contentSessionId, project, prompt) │
│ │
│ Database state: │
│ ├─ content_session_id: "user-session-123" │
│ └─ memory_session_id: NULL (not yet captured) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 2. SDKAgent starts, checks hasRealMemorySessionId │
│ const hasReal = memorySessionId !== null │
│ → FALSE (it's NULL) │
│ → Resume NOT used (fresh SDK session) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 3. First SDK message arrives with session_id │
│ updateMemorySessionId(sessionDbId, "sdk-gen-abc123") │
│ │
│ Database state: │
│ ├─ content_session_id: "user-session-123" │
│ └─ memory_session_id: "sdk-gen-abc123" (real!) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Subsequent prompts use resume │
│ const hasReal = memorySessionId !== null │
│ → TRUE (it's not NULL) │
│ → Resume parameter: { resume: "sdk-gen-abc123" } │
└─────────────────────────────────────────────────────────────┘
```
### Observation Storage
**CRITICAL**: Observations are stored with `contentSessionId`, NOT the captured SDK `memorySessionId`.
```typescript
// SDKAgent.ts line 332-333
this.dbManager.getSessionStore().storeObservation(
session.contentSessionId, // ← contentSessionId, not memorySessionId!
session.project,
obs,
// ...
);
```
Even though the parameter is named `memorySessionId`, it receives `contentSessionId`. This means:
- Database column: `observations.memory_session_id`
- Stored value: `contentSessionId` (the user's session ID)
- Foreign key: References `sdk_sessions.memory_session_id`
The observations are linked to the session via `contentSessionId`, which remains constant throughout the session lifecycle.
## Key Invariants
### 1. NULL-Based Detection
```typescript
const hasRealMemorySessionId = session.memorySessionId !== null;
```
- When `memorySessionId === null` → Not yet captured
- When `memorySessionId !== null` → Real SDK session captured
### 2. Resume Safety
**NEVER** use `contentSessionId` for resume:
```typescript
// ❌ FORBIDDEN - Would resume user's session instead of memory session!
query({ resume: contentSessionId })
// ✅ CORRECT - Only resume when we have real memory session ID
query({
...(hasRealMemorySessionId && { resume: memorySessionId })
})
```
### 3. Session Isolation
- Each `contentSessionId` maps to exactly one database session
- Each database session has one `memorySessionId` (initially NULL, then captured)
- Observations from different content sessions must NEVER mix
### 4. Foreign Key Integrity
- Observations reference `sdk_sessions.memory_session_id`
- Initially, `sdk_sessions.memory_session_id` is NULL (no observations can be stored yet)
- When SDK session ID is captured, `sdk_sessions.memory_session_id` is set to the real value
- Observations are stored using `contentSessionId` and remain retrievable via `contentSessionId`
## Testing Strategy
The test suite validates all critical invariants:
### Test File
`tests/session_id_usage_validation.test.ts`
### Test Categories
1. **NULL-Based Detection** - Validates `hasRealMemorySessionId` logic
2. **Observation Storage** - Confirms observations use `contentSessionId`
3. **Resume Safety** - Prevents `contentSessionId` from being used for resume
4. **Cross-Contamination Prevention** - Ensures session isolation
5. **Foreign Key Integrity** - Validates cascade behavior
6. **Session Lifecycle** - Tests create → capture → resume flow
7. **Edge Cases** - Handles NULL, duplicate IDs, etc.
### Running Tests
```bash
# Run all session ID tests
bun test tests/session_id_usage_validation.test.ts
# Run all tests
bun test
# Run with verbose output
bun test --verbose
```
## Common Pitfalls
### ❌ Using memorySessionId for observations
```typescript
// WRONG - Don't use the captured SDK session ID
storeObservation(session.memorySessionId, ...)
```
### ❌ Resuming without checking for NULL
```typescript
// WRONG - memorySessionId could be NULL!
if (session.memorySessionId) {
query({ resume: session.memorySessionId })
}
```
### ❌ Assuming memorySessionId is always set
```typescript
// WRONG - Can be NULL before SDK session is captured
const resumeId = session.memorySessionId
```
## Correct Usage Patterns
### ✅ Storing observations
```typescript
// Always use contentSessionId
storeObservation(session.contentSessionId, project, obs, ...)
```
### ✅ Checking for real memory session ID
```typescript
const hasRealMemorySessionId = session.memorySessionId !== null;
```
### ✅ Using resume parameter
```typescript
query({
prompt: messageGenerator,
options: {
...(hasRealMemorySessionId && { resume: session.memorySessionId }),
// ... other options
}
})
```
## Debugging Tips
### Check session state
```sql
-- See both session IDs
SELECT
id,
content_session_id,
memory_session_id,
CASE
WHEN memory_session_id IS NULL THEN 'NOT_CAPTURED'
ELSE 'CAPTURED'
END as state
FROM sdk_sessions
WHERE content_session_id = 'your-session-id';
```
### Find orphaned observations
```sql
-- Should return 0 rows if FK integrity is maintained
SELECT o.*
FROM observations o
LEFT JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id
WHERE s.id IS NULL;
```
### Verify observation linkage
```sql
-- See which observations belong to a session
SELECT
o.id,
o.title,
o.memory_session_id,
s.content_session_id,
s.memory_session_id as session_memory_id
FROM observations o
JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id
WHERE s.content_session_id = 'your-session-id';
```
## References
- **Implementation**: `src/services/worker/SDKAgent.ts` (lines 72-94)
- **Database Schema**: `src/services/sqlite/SessionStore.ts` (line 95-104)
- **Tests**: `tests/session_id_usage_validation.test.ts`
- **Related Tests**: `tests/session_id_refactor.test.ts`

79
.agent/services/claude-mem/docs/VERSION_FIX.md Normal file
View File

@@ -0,0 +1,79 @@
# Version Consistency Fix (Issue #XXX)
## Problem
Version mismatch between plugin and worker caused infinite restart loop:
- Plugin version: 9.0.0 (from plugin/.claude-plugin/plugin.json)
- Worker binary version: 8.5.9 (hardcoded in bundled worker-service.cjs)
This triggered the auto-restart mechanism on every hook call, which killed the SDK generator before it could complete the Claude API call to generate observations. Result: 0 observations were ever saved to the database despite hooks firing successfully.
## Root Cause
The `plugin/package.json` file had version `8.5.10` instead of `9.0.0`. When the project was last built, the build script correctly injected the version from root `package.json` into the bundled worker service. However, the `plugin/package.json` was manually created/edited and fell out of sync.
At runtime:
1. Worker service reads version from `~/.claude/plugins/marketplaces/thedotmack/package.json` → gets `8.5.10`
2. Running worker returns built-in version via `/api/version` → returns `8.5.9` (from old build)
3. Version check in `worker-service.ts` start command detects mismatch
4. Auto-restart triggered on every hook call
5. Observations never saved
## Solution
1. Updated `plugin/package.json` from version `8.5.10` to `9.0.0`
2. Rebuilt all hooks and worker service to inject correct version (`9.0.0`) into bundled artifacts
3. Added comprehensive test suite to prevent future version mismatches
## Verification
All versions now match:
```
Root package.json: 9.0.0 ✓
plugin/package.json: 9.0.0 ✓
plugin.json: 9.0.0 ✓
marketplace.json: 9.0.0 ✓
worker-service.cjs: 9.0.0 ✓
```
## Prevention
To prevent this issue in the future:
1. **Automated Build Process**: The `scripts/build-hooks.js` now regenerates `plugin/package.json` automatically with the correct version from root `package.json`
2. **Version Consistency Tests**: Added `tests/infrastructure/version-consistency.test.ts` to verify all version sources match
3. **Version Management Best Practices**:
- NEVER manually edit `plugin/package.json` - it's auto-generated during build
- Always update version in root `package.json` only
- Run `npm run build` after version changes
- The build script will sync the version to all necessary locations
## Files Changed
- `plugin/package.json` - Updated version from 8.5.10 to 9.0.0
- `plugin/scripts/worker-service.cjs` - Rebuilt with version 9.0.0 injected
- `plugin/scripts/mcp-server.cjs` - Rebuilt with version 9.0.0 injected
- `plugin/scripts/*.js` (hooks) - Rebuilt with version 9.0.0 injected
- `tests/infrastructure/version-consistency.test.ts` - New test suite
## Testing
Run the version consistency test:
```bash
npm run test:infra
```
Or manually verify:
```bash
node -e "
const fs = require('fs');
const rootPkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
const pluginPkg = JSON.parse(fs.readFileSync('plugin/package.json', 'utf-8'));
const workerContent = fs.readFileSync('plugin/scripts/worker-service.cjs', 'utf-8');
const workerMatch = workerContent.match(/Bre=\"([0-9.]+)\"/);
console.log('Root:', rootPkg.version);
console.log('Plugin:', pluginPkg.version);
console.log('Worker:', workerMatch ? workerMatch[1] : 'NOT_FOUND');
"
```
## Related Code Locations
- **Version Injection**: `scripts/build-hooks.js` line 43-45, 105, 130, 155, 178
- **Version Check**: `src/services/infrastructure/HealthMonitor.ts` line 133-143
- **Auto-Restart Logic**: `src/services/worker-service.ts` line 627-645
- **Runtime Version Read**: `src/shared/worker-utils.ts` line 73-76, 82-91

48
.agent/services/claude-mem/docs/anti-pattern-cleanup-plan.md Normal file
View File

@@ -0,0 +1,48 @@
# Error Handling Anti-Pattern Cleanup Plan
**Total: 132 anti-patterns to fix**
Run detector: `bun run scripts/anti-pattern-test/detect-error-handling-antipatterns.ts`
## Progress Tracker
- [ ] worker-service.ts (36 issues)
- [ ] SearchManager.ts (28 issues)
- [ ] SessionStore.ts (18 issues)
- [ ] import-xml-observations.ts (7 issues)
- [ ] ChromaSync.ts (6 issues)
- [ ] BranchManager.ts (5 issues)
- [ ] mcp-server.ts (5 issues)
- [ ] logger.ts (3 issues)
- [ ] useContextPreview.ts (3 issues)
- [ ] SessionRoutes.ts (3 issues)
- [ ] ModeManager.ts (3 issues)
- [ ] context-generator.ts (3 issues)
- [ ] useTheme.ts (2 issues)
- [ ] useSSE.ts (2 issues)
- [ ] usePagination.ts (2 issues)
- [ ] SessionManager.ts (2 issues)
- [ ] prompts.ts (2 issues)
- [ ] useStats.ts (1 issue)
- [ ] useSettings.ts (1 issue)
- [ ] timeline-formatting.ts (1 issue)
- [ ] paths.ts (1 issue)
- [ ] SettingsDefaultsManager.ts (1 issue)
- [ ] SettingsRoutes.ts (1 issue)
- [ ] BaseRouteHandler.ts (1 issue)
- [ ] SettingsManager.ts (1 issue)
- [ ] SDKAgent.ts (1 issue)
- [ ] PaginationHelper.ts (1 issue)
- [ ] OpenRouterAgent.ts (1 issue)
- [ ] GeminiAgent.ts (1 issue)
- [ ] SessionQueueProcessor.ts (1 issue)
## Final Verification
- [ ] Run detector and confirm 0 issues (132 approved overrides remain)
- [ ] All tests pass
- [ ] Commit changes
## Notes
All severity designators removed from detector - every anti-pattern is treated as critical.

98
.agent/services/claude-mem/docs/bug-fixes/windows-spaces-issue.md Normal file
View File

@@ -0,0 +1,98 @@
---
Title: Bug: SDK Agent fails on Windows when username contains spaces
---
## Bug Report
**Summary:** Claude SDK Agent fails to start on Windows when the user's path contains spaces (e.g., `C:\Users\Anderson Wang\`), causing PostToolUse hooks to hang indefinitely.
**Severity:** High - Core functionality broken
**Affected Platform:** Windows only
---
## Symptoms
PostToolUse hook displays `(1/2 done)` indefinitely. Worker logs show:
```
ERROR [SESSION] Generator failed {provider=claude, error=Claude Code process exited with code 1}
ERROR [SESSION] Generator exited unexpectedly
```
---
## Root Cause
Two issues in the Windows code path:
1. **`SDKAgent.ts`** - Returns full auto-detected path with spaces:
```
C:\Users\Anderson Wang\AppData\Roaming\npm\claude.cmd
```
2. **`ProcessRegistry.ts`** - Node.js `spawn()` cannot directly execute `.cmd` files when the path contains spaces
---
## Proposed Fix
### File 1: `src/services/worker/SDKAgent.ts`
On Windows, prefer `claude.cmd` via PATH instead of full auto-detected path:
```typescript
// On Windows, prefer "claude.cmd" (via PATH) to avoid spawn issues with spaces in paths
if (process.platform === 'win32') {
try {
execSync('where claude.cmd', { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
return 'claude.cmd'; // Let Windows resolve via PATHEXT
} catch {
// Fall through to generic error
}
}
```
### File 2: `src/services/worker/ProcessRegistry.ts`
Use `cmd.exe /d /c` wrapper for .cmd files on Windows:
```typescript
const useCmdWrapper = process.platform === 'win32' && spawnOptions.command.endsWith('.cmd');
if (useCmdWrapper) {
child = spawn('cmd.exe', ['/d', '/c', spawnOptions.command, ...spawnOptions.args], {
cwd: spawnOptions.cwd,
env: spawnOptions.env,
stdio: ['pipe', 'pipe', 'pipe'],
signal: spawnOptions.signal,
windowsHide: true
});
}
```
---
## Why This Works
- **PATHEXT Resolution:** Windows searches PATH and tries each extension in PATHEXT automatically
- **cmd.exe wrapper:** Properly handles paths with spaces and argument passing
- **Avoids shell parsing:** Using direct arguments instead of `shell: true` prevents empty string misparsing
---
## Testing
Verified on Windows 11 with username containing spaces:
- PostToolUse hook completes successfully
- Observations are stored to database
- No more "process exited with code 1" errors
---
## Additional Notes
- Maintains backward compatibility with `CLAUDE_CODE_PATH` setting
- No impact on non-Windows platforms
- Related to Issue #733 (credential isolation) - separate fix

128
.agent/services/claude-mem/docs/context/agent-sdk-v2-examples.ts Normal file
View File

@@ -0,0 +1,128 @@
/**
* Claude Agent SDK V2 Examples
*
* The V2 API provides a session-based interface with separate send()/receive(),
* ideal for multi-turn conversations. Run with: npx tsx v2-examples.ts
*/
import {
unstable_v2_createSession,
unstable_v2_resumeSession,
unstable_v2_prompt,
} from '@anthropic-ai/claude-agent-sdk';
async function main() {
const example = process.argv[2] || 'basic';
switch (example) {
case 'basic':
await basicSession();
break;
case 'multi-turn':
await multiTurn();
break;
case 'one-shot':
await oneShot();
break;
case 'resume':
await sessionResume();
break;
default:
console.log('Usage: npx tsx v2-examples.ts [basic|multi-turn|one-shot|resume]');
}
}
// Basic session with send/receive pattern
async function basicSession() {
console.log('=== Basic Session ===\n');
await using session = unstable_v2_createSession({ model: 'sonnet' });
await session.send('Hello! Introduce yourself in one sentence.');
for await (const msg of session.receive()) {
if (msg.type === 'assistant') {
const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
console.log(`Claude: ${text?.text}`);
}
}
}
// Multi-turn conversation - V2's key advantage
async function multiTurn() {
console.log('=== Multi-Turn Conversation ===\n');
await using session = unstable_v2_createSession({ model: 'sonnet' });
// Turn 1
await session.send('What is 5 + 3? Just the number.');
for await (const msg of session.receive()) {
if (msg.type === 'assistant') {
const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
console.log(`Turn 1: ${text?.text}`);
}
}
// Turn 2 - Claude remembers context
await session.send('Multiply that by 2. Just the number.');
for await (const msg of session.receive()) {
if (msg.type === 'assistant') {
const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
console.log(`Turn 2: ${text?.text}`);
}
}
}
// One-shot convenience function
async function oneShot() {
console.log('=== One-Shot Prompt ===\n');
const result = await unstable_v2_prompt('What is the capital of France? One word.', { model: 'sonnet' });
if (result.subtype === 'success') {
console.log(`Answer: ${result.result}`);
console.log(`Cost: $${result.total_cost_usd.toFixed(4)}`);
}
}
// Session resume - persist context across sessions
async function sessionResume() {
console.log('=== Session Resume ===\n');
let sessionId: string | undefined;
// First session - establish a memory
{
await using session = unstable_v2_createSession({ model: 'sonnet' });
console.log('[Session 1] Telling Claude my favorite color...');
await session.send('My favorite color is blue. Remember this!');
for await (const msg of session.receive()) {
if (msg.type === 'system' && msg.subtype === 'init') {
sessionId = msg.session_id;
console.log(`[Session 1] ID: ${sessionId}`);
}
if (msg.type === 'assistant') {
const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
console.log(`[Session 1] Claude: ${text?.text}\n`);
}
}
}
console.log('--- Session closed. Time passes... ---\n');
// Resume and verify Claude remembers
{
await using session = unstable_v2_resumeSession(sessionId!, { model: 'sonnet' });
console.log('[Session 2] Resuming and asking Claude...');
await session.send('What is my favorite color?');
for await (const msg of session.receive()) {
if (msg.type === 'assistant') {
const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
console.log(`[Session 2] Claude: ${text?.text}`);
}
}
}
}
main().catch(console.error);

390
.agent/services/claude-mem/docs/context/agent-sdk-v2-preview.md Normal file
View File

@@ -0,0 +1,390 @@
# TypeScript SDK V2 interface (preview)
Preview of the simplified V2 TypeScript Agent SDK, with session-based send/receive patterns for multi-turn conversations.
---
<Warning>
The V2 interface is an **unstable preview**. APIs may change based on feedback before becoming stable. Some features like session forking are only available in the [V1 SDK](/docs/en/agent-sdk/typescript).
</Warning>
The V2 Claude Agent TypeScript SDK removes the need for async generators and yield coordination. This makes multi-turn conversations simpler—instead of managing generator state across turns, each turn is a separate `send()`/`receive()` cycle. The API surface reduces to three concepts:
- `createSession()` / `resumeSession()`: Start or continue a conversation
- `session.send()`: Send a message
- `session.receive()`: Get the response
## Installation
The V2 interface is included in the existing SDK package:
```bash
npm install @anthropic-ai/claude-agent-sdk
```
## Quick start
### One-shot prompt
For simple single-turn queries where you don't need to maintain a session, use `unstable_v2_prompt()`. This example sends a math question and logs the answer:
```typescript
import { unstable_v2_prompt } from '@anthropic-ai/claude-agent-sdk'
const result = await unstable_v2_prompt('What is 2 + 2?', {
model: 'claude-sonnet-4-5-20250929'
})
console.log(result.result)
```
<details>
<summary>See the same operation in V1</summary>
```typescript
import { query } from '@anthropic-ai/claude-agent-sdk'
const q = query({
prompt: 'What is 2 + 2?',
options: { model: 'claude-sonnet-4-5-20250929' }
})
for await (const msg of q) {
if (msg.type === 'result') {
console.log(msg.result)
}
}
```
</details>
### Basic session
For interactions beyond a single prompt, create a session. V2 separates sending and receiving into distinct steps:
- `send()` dispatches your message
- `receive()` streams back the response
This explicit separation makes it easier to add logic between turns (like processing responses before sending follow-ups).
The example below creates a session, sends "Hello!" to Claude, and prints the text response. It uses [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management) (TypeScript 5.2+) to automatically close the session when the block exits. You can also call `session.close()` manually.
```typescript
import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
await using session = unstable_v2_createSession({
model: 'claude-sonnet-4-5-20250929'
})
await session.send('Hello!')
for await (const msg of session.receive()) {
// Filter for assistant messages to get human-readable output
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log(text)
}
}
```
<details>
<summary>See the same operation in V1</summary>
In V1, both input and output flow through a single async generator. For a basic prompt this looks similar, but adding multi-turn logic requires restructuring to use an input generator.
```typescript
import { query } from '@anthropic-ai/claude-agent-sdk'
const q = query({
prompt: 'Hello!',
options: { model: 'claude-sonnet-4-5-20250929' }
})
for await (const msg of q) {
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log(text)
}
}
```
</details>
### Multi-turn conversation
Sessions persist context across multiple exchanges. To continue a conversation, call `send()` again on the same session. Claude remembers the previous turns.
This example asks a math question, then asks a follow-up that references the previous answer:
```typescript
import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
await using session = unstable_v2_createSession({
model: 'claude-sonnet-4-5-20250929'
})
// Turn 1
await session.send('What is 5 + 3?')
for await (const msg of session.receive()) {
// Filter for assistant messages to get human-readable output
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log(text)
}
}
// Turn 2
await session.send('Multiply that by 2')
for await (const msg of session.receive()) {
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log(text)
}
}
```
<details>
<summary>See the same operation in V1</summary>
```typescript
import { query } from '@anthropic-ai/claude-agent-sdk'
// Must create an async iterable to feed messages
async function* createInputStream() {
yield {
type: 'user',
session_id: '',
message: { role: 'user', content: [{ type: 'text', text: 'What is 5 + 3?' }] },
parent_tool_use_id: null
}
// Must coordinate when to yield next message
yield {
type: 'user',
session_id: '',
message: { role: 'user', content: [{ type: 'text', text: 'Multiply by 2' }] },
parent_tool_use_id: null
}
}
const q = query({
prompt: createInputStream(),
options: { model: 'claude-sonnet-4-5-20250929' }
})
for await (const msg of q) {
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log(text)
}
}
```
</details>
### Session resume
If you have a session ID from a previous interaction, you can resume it later. This is useful for long-running workflows or when you need to persist conversations across application restarts.
This example creates a session, stores its ID, closes it, then resumes the conversation:
```typescript
import {
unstable_v2_createSession,
unstable_v2_resumeSession,
type SDKMessage
} from '@anthropic-ai/claude-agent-sdk'
// Helper to extract text from assistant messages
function getAssistantText(msg: SDKMessage): string | null {
if (msg.type !== 'assistant') return null
return msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
}
// Create initial session and have a conversation
const session = unstable_v2_createSession({
model: 'claude-sonnet-4-5-20250929'
})
await session.send('Remember this number: 42')
// Get the session ID from any received message
let sessionId: string | undefined
for await (const msg of session.receive()) {
sessionId = msg.session_id
const text = getAssistantText(msg)
if (text) console.log('Initial response:', text)
}
console.log('Session ID:', sessionId)
session.close()
// Later: resume the session using the stored ID
await using resumedSession = unstable_v2_resumeSession(sessionId!, {
model: 'claude-sonnet-4-5-20250929'
})
await resumedSession.send('What number did I ask you to remember?')
for await (const msg of resumedSession.receive()) {
const text = getAssistantText(msg)
if (text) console.log('Resumed response:', text)
}
```
<details>
<summary>See the same operation in V1</summary>
```typescript
import { query } from '@anthropic-ai/claude-agent-sdk'
// Create initial session
const initialQuery = query({
prompt: 'Remember this number: 42',
options: { model: 'claude-sonnet-4-5-20250929' }
})
// Get session ID from any message
let sessionId: string | undefined
for await (const msg of initialQuery) {
sessionId = msg.session_id
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log('Initial response:', text)
}
}
console.log('Session ID:', sessionId)
// Later: resume the session
const resumedQuery = query({
prompt: 'What number did I ask you to remember?',
options: {
model: 'claude-sonnet-4-5-20250929',
resume: sessionId
}
})
for await (const msg of resumedQuery) {
if (msg.type === 'assistant') {
const text = msg.message.content
.filter(block => block.type === 'text')
.map(block => block.text)
.join('')
console.log('Resumed response:', text)
}
}
```
</details>
### Cleanup
Sessions can be closed manually or automatically using [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management), a TypeScript 5.2+ feature for automatic resource cleanup. If you're using an older TypeScript version or encounter compatibility issues, use manual cleanup instead.
**Automatic cleanup (TypeScript 5.2+):**
```typescript
import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
await using session = unstable_v2_createSession({
model: 'claude-sonnet-4-5-20250929'
})
// Session closes automatically when the block exits
```
**Manual cleanup:**
```typescript
import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'
const session = unstable_v2_createSession({
model: 'claude-sonnet-4-5-20250929'
})
// ... use the session ...
session.close()
```
## API reference
### `unstable_v2_createSession()`
Creates a new session for multi-turn conversations.
```typescript
function unstable_v2_createSession(options: {
model: string;
// Additional options supported
}): Session
```
### `unstable_v2_resumeSession()`
Resumes an existing session by ID.
```typescript
function unstable_v2_resumeSession(
sessionId: string,
options: {
model: string;
// Additional options supported
}
): Session
```
### `unstable_v2_prompt()`
One-shot convenience function for single-turn queries.
```typescript
function unstable_v2_prompt(
prompt: string,
options: {
model: string;
// Additional options supported
}
): Promise<Result>
```
### Session interface
```typescript
interface Session {
send(message: string): Promise<void>;
receive(): AsyncGenerator<SDKMessage>;
close(): void;
}
```
## Feature availability
Not all V1 features are available in V2 yet. The following require using the [V1 SDK](/docs/en/agent-sdk/typescript):
- Session forking (`forkSession` option)
- Some advanced streaming input patterns
## Feedback
Share your feedback on the V2 interface before it becomes stable. Report issues and suggestions through [GitHub Issues](https://github.com/anthropics/claude-code/issues).
## See also
- [TypeScript SDK reference (V1)](/docs/en/agent-sdk/typescript) - Full V1 SDK documentation
- [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts
- [V2 examples on GitHub](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world-v2) - Working code examples

586
.agent/services/claude-mem/docs/context/cursor-hooks-reference.md Normal file
View File

@@ -0,0 +1,586 @@
# Hooks
Hooks let you observe, control, and extend the agent loop using custom scripts. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block, or modify behavior.
With hooks, you can:
- Run formatters after edits
- Add analytics for events
- Scan for PII or secrets
- Gate risky operations (e.g., SQL writes)
<Tip>
Looking for ready-to-use integrations? See [Partner Integrations](#partner-integrations) for security, governance, and secrets management solutions from our ecosystem partners.
</Tip>
## Agent and Tab Support
Hooks work with both **Cursor Agent** (Cmd+K/Agent Chat) and **Cursor Tab** (inline completions), but they use different hook events:
**Agent (Cmd+K/Agent Chat)** uses the standard hooks:
- `beforeShellExecution` / `afterShellExecution` - Control shell commands
- `beforeMCPExecution` / `afterMCPExecution` - Control MCP tool usage
- `beforeReadFile` / `afterFileEdit` - Control file access and edits
- `beforeSubmitPrompt` - Validate prompts before submission
- `stop` - Handle agent completion
- `afterAgentResponse` / `afterAgentThought` - Track agent responses
**Tab (inline completions)** uses specialized hooks:
- `beforeTabFileRead` - Control file access for Tab completions
- `afterTabFileEdit` - Post-process Tab edits
These separate hooks allow different policies for autonomous Tab operations versus user-directed Agent operations.
## Quickstart
Create a `hooks.json` file. You can create it at the project level (`<project>/.cursor/hooks.json`) or in your home directory (`~/.cursor/hooks.json`). Project-level hooks apply only to that specific project, while home directory hooks apply globally.
```json
{
"version": 1,
"hooks": {
"afterFileEdit": [{ "command": "./hooks/format.sh" }]
}
}
```
Create your hook script at `~/.cursor/hooks/format.sh`:
```bash
#!/bin/bash
# Read input, do something, exit 0
cat > /dev/null
exit 0
```
Make it executable:
```bash
chmod +x ~/.cursor/hooks/format.sh
```
Restart Cursor. Your hook now runs after every file edit.
## Examples
<CodeGroup>
```json title="hooks.json"
{
"version": 1,
"hooks": {
"beforeShellExecution": [
{
"command": "./hooks/audit.sh"
},
{
"command": "./hooks/block-git.sh"
}
],
"beforeMCPExecution": [
{
"command": "./hooks/audit.sh"
}
],
"afterShellExecution": [
{
"command": "./hooks/audit.sh"
}
],
"afterMCPExecution": [
{
"command": "./hooks/audit.sh"
}
],
"afterFileEdit": [
{
"command": "./hooks/audit.sh"
}
],
"beforeSubmitPrompt": [
{
"command": "./hooks/audit.sh"
}
],
"stop": [
{
"command": "./hooks/audit.sh"
}
],
"beforeTabFileRead": [
{
"command": "./hooks/redact-secrets-tab.sh"
}
],
"afterTabFileEdit": [
{
"command": "./hooks/format-tab.sh"
}
]
}
}
```
```sh title="audit.sh"
#!/bin/bash
# audit.sh - Hook script that writes all JSON input to /tmp/agent-audit.log
# This script is designed to be called by Cursor's hooks system for auditing purposes
# Read JSON input from stdin
json_input=$(cat)
# Create timestamp for the log entry
timestamp=$(date '+%Y-%m-%d %H:%M:%S')
# Create the log directory if it doesn't exist
mkdir -p "$(dirname /tmp/agent-audit.log)"
# Write the timestamped JSON entry to the audit log
echo "[$timestamp] $json_input" >> /tmp/agent-audit.log
# Exit successfully
exit 0
```
```sh title="block-git.sh"
#!/bin/bash
# Hook to block git commands and redirect to gh tool usage
# This hook implements the beforeShellExecution hook from the Cursor Hooks Spec
# Initialize debug logging
echo "Hook execution started" >> /tmp/hooks.log
# Read JSON input from stdin
input=$(cat)
echo "Received input: $input" >> /tmp/hooks.log
# Parse the command from the JSON input
command=$(echo "$input" | jq -r '.command // empty')
echo "Parsed command: '$command'" >> /tmp/hooks.log
# Check if the command contains 'git' or 'gh'
if [[ "$command" =~ git[[:space:]] ]] || [[ "$command" == "git" ]]; then
echo "Git command detected - blocking: '$command'" >> /tmp/hooks.log
# Block the git command and provide guidance to use gh tool instead
cat << EOF
{
"continue": true,
"permission": "deny",
"user_message": "Git command blocked. Please use the GitHub CLI (gh) tool instead.",
"agent_message": "The git command '$command' has been blocked by a hook. Instead of using raw git commands, please use the 'gh' tool which provides better integration with GitHub and follows best practices. For example:\n- Instead of 'git clone', use 'gh repo clone'\n- Instead of 'git push', use 'gh repo sync' or the appropriate gh command\n- For other git operations, check if there's an equivalent gh command or use the GitHub web interface\n\nThis helps maintain consistency and leverages GitHub's enhanced tooling."
}
EOF
elif [[ "$command" =~ gh[[:space:]] ]] || [[ "$command" == "gh" ]]; then
echo "GitHub CLI command detected - asking for permission: '$command'" >> /tmp/hooks.log
# Ask for permission for gh commands
cat << EOF
{
"continue": true,
"permission": "ask",
"user_message": "GitHub CLI command requires permission: $command",
"agent_message": "The command '$command' uses the GitHub CLI (gh) which can interact with your GitHub repositories and account. Please review and approve this command if you want to proceed."
}
EOF
else
echo "Non-git/non-gh command detected - allowing: '$command'" >> /tmp/hooks.log
# Allow non-git/non-gh commands
cat << EOF
{
"continue": true,
"permission": "allow"
}
EOF
fi
```
</CodeGroup>
## Partner Integrations
We partner with ecosystem vendors who have built hooks support with Cursor. These integrations cover security scanning, governance, secrets management, and more.
### MCP governance and visibility
| Partner | Description |
|---------|-------------|
| [MintMCP](https://www.mintmcp.com/blog/mcp-governance-cursor-hooks) | Build a complete inventory of MCP servers, monitor tool usage patterns, and scan responses for sensitive data before it reaches the AI model. |
| [Oasis Security](https://www.oasis.security/blog/cursor-oasis-governing-agentic-access) | Enforce least-privilege policies on AI agent actions and maintain full audit trails across enterprise systems. |
| [Runlayer](https://www.runlayer.com/blog/cursor-hooks) | Wrap MCP tools and integrate with their MCP broker for centralized control and visibility over agent-to-tool interactions. |
### Code security and best practices
| Partner | Description |
|---------|-------------|
| [Corridor](https://corridor.dev/blog/corridor-cursor-hooks/) | Get real-time feedback on code implementation and security design decisions as code is being written. |
| [Semgrep](https://semgrep.dev/blog/2025/cursor-hooks-mcp-server) | Automatically scan AI-generated code for vulnerabilities with real-time feedback to regenerate code until security issues are resolved. |
### Dependency security
| Partner | Description |
|---------|-------------|
| [Endor Labs](https://www.endorlabs.com/learn/bringing-malware-detection-into-ai-coding-workflows-with-cursor-hooks) | Intercept package installations and scan for malicious dependencies, preventing supply chain attacks before they enter your codebase. |
### Agent security and safety
| Partner | Description |
|---------|-------------|
| [Snyk](https://snyk.io/blog/evo-agent-guard-cursor-integration/) | Review agent actions in real-time with Evo Agent Guard, detecting and preventing issues like prompt injection and dangerous tool calls. |
### Secrets management
| Partner | Description |
|---------|-------------|
| [1Password](https://marketplace.1password.com/integration/cursor-hooks) | Validate that environment files from 1Password Environments are properly mounted before shell commands execute, enabling just-in-time secrets access without writing credentials to disk. |
For more details about our hooks partners, see the [Hooks for security and platform teams](/blog/hooks-partners) blog post.
## Configuration
Define hooks in a `hooks.json` file. Configuration can exist at multiple levels; higher-priority sources override lower ones:
```sh
~/.cursor/
├── hooks.json
└── hooks/
├── audit.sh
└── block-git.sh
```
- **Global** (Enterprise-managed):
- macOS: `/Library/Application Support/Cursor/hooks.json`
- Linux/WSL: `/etc/cursor/hooks.json`
- Windows: `C:\\ProgramData\\Cursor\\hooks.json`
- **Project Directory** (Project-specific):
- `<project-root>/.cursor/hooks.json`
- Project hooks run in any trusted workspace and are checked into version control with your project
- **Home Directory** (User-specific):
- `~/.cursor/hooks.json`
Priority order (highest to lowest): Enterprise → Project → User
The `hooks` object maps hook names to arrays of hook definitions. Each definition currently supports a `command` property that can be a shell string, an absolute path, or a path relative to the `hooks.json` file.
### Configuration file
```json
{
"version": 1,
"hooks": {
"beforeShellExecution": [{ "command": "./script.sh" }],
"afterShellExecution": [{ "command": "./script.sh" }],
"afterMCPExecution": [{ "command": "./script.sh" }],
"afterFileEdit": [{ "command": "./format.sh" }],
"beforeTabFileRead": [{ "command": "./redact-secrets-tab.sh" }],
"afterTabFileEdit": [{ "command": "./format-tab.sh" }]
}
}
```
The Agent hooks (`beforeShellExecution`, `afterShellExecution`, `beforeMCPExecution`, `afterMCPExecution`, `beforeReadFile`, `afterFileEdit`, `beforeSubmitPrompt`, `stop`, `afterAgentResponse`, `afterAgentThought`) apply to Cmd+K and Agent Chat operations. The Tab hooks (`beforeTabFileRead`, `afterTabFileEdit`) apply specifically to inline Tab completions.
## Team Distribution
Hooks can be distributed to team members using project hooks (via version control), MDM tools, or Cursor's cloud distribution system.
### Project Hooks (Version Control)
Project hooks are the simplest way to share hooks with your team. Place a `hooks.json` file at `<project-root>/.cursor/hooks.json` and commit it to your repository. When team members open the project in a trusted workspace, Cursor automatically loads and runs the project hooks.
Project hooks:
- Are stored in version control alongside your code
- Automatically load for all team members in trusted workspaces
- Can be project-specific (e.g., enforce formatting standards for a particular codebase)
- Require the workspace to be trusted to run (for security)
### MDM Distribution
Distribute hooks across your organization using Mobile Device Management (MDM) tools. Place the `hooks.json` file and hook scripts in the target directories on each machine.
**User home directory** (per-user distribution):
- `~/.cursor/hooks.json`
- `~/.cursor/hooks/` (for hook scripts)
**Global directories** (system-wide distribution):
- macOS: `/Library/Application Support/Cursor/hooks.json`
- Linux/WSL: `/etc/cursor/hooks.json`
- Windows: `C:\\ProgramData\\Cursor\\hooks.json`
Note: MDM-based distribution is fully managed by your organization. Cursor does not deploy or manage files through your MDM solution. Ensure your internal IT or security team handles configuration, deployment, and updates in accordance with your organization's policies.
### Cloud Distribution (Enterprise Only)
Enterprise teams can use Cursor's native cloud distribution to automatically sync hooks to all team members. Configure hooks in the [web dashboard](https://cursor.com/dashboard?tab=team-content&section=hooks). Cursor automatically delivers configured hooks to all client machines when team members log in.
Cloud distribution provides:
- Automatic synchronization to all team members (every thirty minutes)
- Operating system targeting for platform-specific hooks
- Centralized management through the dashboard
Enterprise administrators can create, edit, and manage team hooks from the dashboard without requiring access to individual machines.
## Reference
### Common schema
#### Input (all hooks)
All hooks receive a base set of fields in addition to their hook-specific fields:
```json
{
"conversation_id": "string",
"generation_id": "string",
"model": "string",
"hook_event_name": "string",
"cursor_version": "string",
"workspace_roots": ["<path>"],
"user_email": "string | null"
}
```
| Field | Type | Description |
|-------|------|-------------|
| `conversation_id` | string | Stable ID of the conversation across many turns |
| `generation_id` | string | The current generation that changes with every user message |
| `model` | string | The model configured for the composer that triggered the hook |
| `hook_event_name` | string | Which hook is being run |
| `cursor_version` | string | Cursor application version (e.g. "1.7.2") |
| `workspace_roots` | string[] | The list of root folders in the workspace (normally just one, but multiroot workspaces can have multiple) |
| `user_email` | string \| null | Email address of the authenticated user, if available |
### Hook events
#### beforeShellExecution / beforeMCPExecution
Called before any shell command or MCP tool is executed. Return a permission decision.
```json
// beforeShellExecution input
{
"command": "<full terminal command>",
"cwd": "<current working directory>"
}
// beforeMCPExecution input
{
"tool_name": "<tool name>",
"tool_input": "<json params>"
}
// Plus either:
{ "url": "<server url>" }
// Or:
{ "command": "<command string>" }
// Output
{
"permission": "allow" | "deny" | "ask",
"user_message": "<message shown in client>",
"agent_message": "<message sent to agent>"
}
```
#### afterShellExecution
Fires after a shell command executes; useful for auditing or collecting metrics from command output.
```json
// Input
{
"command": "<full terminal command>",
"output": "<full terminal output>",
"duration": 1234
}
```
| Field | Type | Description |
|-------|------|-------------|
| `command` | string | The full terminal command that was executed |
| `output` | string | Full output captured from the terminal |
| `duration` | number | Duration in milliseconds spent executing the shell command (excludes approval wait time) |
#### afterMCPExecution
Fires after an MCP tool executes; includes the tool's input parameters and full JSON result.
```json
// Input
{
"tool_name": "<tool name>",
"tool_input": "<json params>",
"result_json": "<tool result json>",
"duration": 1234
}
```
| Field | Type | Description |
|-------|------|-------------|
| `tool_name` | string | Name of the MCP tool that was executed |
| `tool_input` | string | JSON params string passed to the tool |
| `result_json` | string | JSON string of the tool response |
| `duration` | number | Duration in milliseconds spent executing the MCP tool (excludes approval wait time) |
#### afterFileEdit
Fires after the Agent edits a file; useful for formatters or accounting of agent-written code.
```json
// Input
{
"file_path": "<absolute path>",
"edits": [{ "old_string": "<search>", "new_string": "<replace>" }]
}
```
#### beforeTabFileRead
Called before Tab (inline completions) reads a file. Enable redaction or access control before Tab accesses file contents.
**Key differences from `beforeReadFile`:**
- Only triggered by Tab, not Agent
- Does not include `attachments` field (Tab doesn't use prompt attachments)
- Useful for applying different policies to autonomous Tab operations
```json
// Input
{
"file_path": "<absolute path>",
"content": "<file contents>"
}
// Output
{
"permission": "allow" | "deny"
}
```
#### afterTabFileEdit
Called after Tab (inline completions) edits a file. Useful for formatters or auditing of Tab-written code.
**Key differences from `afterFileEdit`:**
- Only triggered by Tab, not Agent
- Includes detailed edit information: `range`, `old_line`, and `new_line` for precise edit tracking
- Useful for fine-grained formatting or analysis of Tab edits
```json
// Input
{
"file_path": "<absolute path>",
"edits": [
{
"old_string": "<search>",
"new_string": "<replace>",
"range": {
"start_line_number": 10,
"start_column": 5,
"end_line_number": 10,
"end_column": 20
},
"old_line": "<line before edit>",
"new_line": "<line after edit>"
}
]
}
// Output
{
// No output fields currently supported
}
```
#### beforeSubmitPrompt
Called right after user hits send but before backend request. Can prevent submission.
```json
// Input
{
"prompt": "<user prompt text>",
"attachments": [
{
"type": "file" | "rule",
"filePath": "<absolute path>"
}
]
}
// Output
{
"continue": true | false,
"user_message": "<message shown to user when blocked>"
}
```
| Output Field | Type | Description |
|--------------|------|-------------|
| `continue` | boolean | Whether to allow the prompt submission to proceed |
| `user_message` | string (optional) | Message shown to the user when the prompt is blocked |
#### afterAgentResponse
Called after the agent has completed an assistant message.
```json
// Input
{
"text": "<assistant final text>"
}
```
#### afterAgentThought
Called after the agent completes a thinking block. Useful for observing the agent's reasoning process.
```json
// Input
{
"text": "<fully aggregated thinking text>",
"duration_ms": 5000
}
// Output
{
// No output fields currently supported
}
```
| Field | Type | Description |
|-------|------|-------------|
| `text` | string | Fully aggregated thinking text for the completed block |
| `duration_ms` | number (optional) | Duration in milliseconds for the thinking block |
#### stop
Called when the agent loop ends. Can optionally auto-submit a follow-up user message to keep iterating.
```json
// Input
{
"status": "completed" | "aborted" | "error",
"loop_count": 0
}
```
```json
// Output
{
"followup_message": "<message text>"
}
```
- The optional `followup_message` is a string. When provided and non-empty, Cursor will automatically submit it as the next user message. This enables loop-style flows (e.g., iterate until a goal is met).
- The `loop_count` field indicates how many times the stop hook has already triggered an automatic follow-up for this conversation (starts at 0). To prevent infinite loops, a maximum of 5 auto follow-ups is enforced.
## Troubleshooting
**How to confirm hooks are active**
There is a Hooks tab in Cursor Settings to debug configured and executed hooks, as well as a Hooks output channel to see errors.
**If hooks are not working**
- Restart Cursor to ensure the hooks service is running.
- Ensure hook script paths are relative to `hooks.json` when using relative paths.

338
.agent/services/claude-mem/docs/context/hooks-reference-2026-01-07.md Normal file
View File

@@ -0,0 +1,338 @@
# Get started with Claude Code hooks
> Learn how to customize and extend Claude Code's behavior by registering shell commands
Claude Code hooks are user-defined shell commands that execute at various points
in Claude Code's lifecycle. Hooks provide deterministic control over Claude
Code's behavior, ensuring certain actions always happen rather than relying on
the LLM to choose to run them.
<Tip>
For reference documentation on hooks, see [Hooks reference](/en/hooks).
</Tip>
Example use cases for hooks include:
* **Notifications**: Customize how you get notified when Claude Code is awaiting
your input or permission to run something.
* **Automatic formatting**: Run `prettier` on .ts files, `gofmt` on .go files,
etc. after every file edit.
* **Logging**: Track and count all executed commands for compliance or
debugging.
* **Feedback**: Provide automated feedback when Claude Code produces code that
does not follow your codebase conventions.
* **Custom permissions**: Block modifications to production files or sensitive
directories.
By encoding these rules as hooks rather than prompting instructions, you turn
suggestions into app-level code that executes every time it is expected to run.
<Warning>
You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials.
For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them.
For full security best practices, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
</Warning>
## Hook Events Overview
Claude Code provides several hook events that run at different points in the
workflow:
* **PreToolUse**: Runs before tool calls (can block them)
* **PermissionRequest**: Runs when a permission dialog is shown (can allow or deny)
* **PostToolUse**: Runs after tool calls complete
* **UserPromptSubmit**: Runs when the user submits a prompt, before Claude processes it
* **Notification**: Runs when Claude Code sends notifications
* **Stop**: Runs when Claude Code finishes responding
* **SubagentStop**: Runs when subagent tasks complete
* **PreCompact**: Runs before Claude Code is about to run a compact operation
* **SessionStart**: Runs when Claude Code starts a new session or resumes an existing session
* **SessionEnd**: Runs when Claude Code session ends
Each event receives different data and can control Claude's behavior in
different ways.
## Quickstart
In this quickstart, you'll add a hook that logs the shell commands that Claude
Code runs.
### Prerequisites
Install `jq` for JSON processing in the command line.
### Step 1: Open hooks configuration
Run the `/hooks` [slash command](/en/slash-commands) and select
the `PreToolUse` hook event.
`PreToolUse` hooks run before tool calls and can block them while providing
Claude feedback on what to do differently.
### Step 2: Add a matcher
Select `+ Add new matcher…` to run your hook only on Bash tool calls.
Type `Bash` for the matcher.
<Note>You can use `*` to match all tools.</Note>
### Step 3: Add the hook
Select `+ Add new hook…` and enter this command:
```bash theme={null}
jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt
```
### Step 4: Save your configuration
For storage location, select `User settings` since you're logging to your home
directory. This hook will then apply to all projects, not just your current
project.
Then press `Esc` until you return to the REPL. Your hook is now registered.
### Step 5: Verify your hook
Run `/hooks` again or check `~/.claude/settings.json` to see your configuration:
```json theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
}
]
}
]
}
}
```
### Step 6: Test your hook
Ask Claude to run a simple command like `ls` and check your log file:
```bash theme={null}
cat ~/.claude/bash-command-log.txt
```
You should see entries like:
```
ls - Lists files and directories
```
## More Examples
<Note>
For a complete example implementation, see the [bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py) in our public codebase.
</Note>
### Code Formatting Hook
Automatically format TypeScript files after editing:
```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
}
]
}
]
}
}
```
### Markdown Formatting Hook
Automatically fix missing language tags and formatting issues in markdown files:
```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
}
]
}
]
}
}
```
Create `.claude/hooks/markdown_formatter.py` with this content:
````python theme={null}
#!/usr/bin/env python3
"""
Markdown formatter for Claude Code output.
Fixes missing language tags and spacing issues while preserving code content.
"""
import json
import sys
import re
import os
def detect_language(code):
"""Best-effort language detection from code content."""
s = code.strip()
# JSON detection
if re.search(r'^\s*[{\[]', s):
try:
json.loads(s)
return 'json'
except:
pass
# Python detection
if re.search(r'^\s*def\s+\w+\s*\(', s, re.M) or \
re.search(r'^\s*(import|from)\s+\w+', s, re.M):
return 'python'
# JavaScript detection
if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', s) or \
re.search(r'=>|console\.(log|error)', s):
return 'javascript'
# Bash detection
if re.search(r'^#!.*\b(bash|sh)\b', s, re.M) or \
re.search(r'\b(if|then|fi|for|in|do|done)\b', s):
return 'bash'
# SQL detection
if re.search(r'\b(SELECT|INSERT|UPDATE|DELETE|CREATE)\s+', s, re.I):
return 'sql'
return 'text'
def format_markdown(content):
"""Format markdown content with language detection."""
# Fix unlabeled code fences
def add_lang_to_fence(match):
indent, info, body, closing = match.groups()
if not info.strip():
lang = detect_language(body)
return f"{indent}```{lang}\n{body}{closing}\n"
return match.group(0)
fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
content = re.sub(fence_pattern, add_lang_to_fence, content)
# Fix excessive blank lines (only outside code fences)
content = re.sub(r'\n{3,}', '\n\n', content)
return content.rstrip() + '\n'
# Main execution
try:
input_data = json.load(sys.stdin)
file_path = input_data.get('tool_input', {}).get('file_path', '')
if not file_path.endswith(('.md', '.mdx')):
sys.exit(0) # Not a markdown file
if os.path.exists(file_path):
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
formatted = format_markdown(content)
if formatted != content:
with open(file_path, 'w', encoding='utf-8') as f:
f.write(formatted)
print(f"✓ Fixed markdown formatting in {file_path}")
except Exception as e:
print(f"Error formatting markdown: {e}", file=sys.stderr)
sys.exit(1)
````
Make the script executable:
```bash theme={null}
chmod +x .claude/hooks/markdown_formatter.py
```
This hook automatically:
* Detects programming languages in unlabeled code blocks
* Adds appropriate language tags for syntax highlighting
* Fixes excessive blank lines while preserving code content
* Only processes markdown files (`.md`, `.mdx`)
### Custom Notification Hook
Get desktop notifications when Claude needs input:
```json theme={null}
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Awaiting your input'"
}
]
}
]
}
}
```
### File Protection Hook
Block edits to sensitive files:
```json theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
}
]
}
]
}
}
```
## Learn more
* For reference documentation on hooks, see [Hooks reference](/en/hooks).
* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference
documentation.
---
> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

146
.agent/services/claude-mem/docs/i18n/.translation-cache.json Normal file
View File

@@ -0,0 +1,146 @@
{
"sourceHash": "c0eb50d6772b5e61",
"lastUpdated": "2025-12-23T00:48:34.035Z",
"translations": {
"zh": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.09515915
},
"ja": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.09678544999999998
},
"pt-br": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.08436794999999998
},
"ko": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.10244419999999999
},
"es": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.0894832
},
"de": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.08818689999999998
},
"fr": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:39:44.891Z",
"costUsd": 0.0855869
},
"nl": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.0943619
},
"ru": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.0944719
},
"pl": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.08966189999999999
},
"cs": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.08897189999999998
},
"uk": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.09968189999999999
},
"tr": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.0969419
},
"ar": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.10445689999999998
},
"he": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:43:09.878Z",
"costUsd": 0.1489769
},
"id": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.08454690000000001
},
"sv": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.09621189999999999
},
"ro": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.10500190000000001
},
"vi": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.1035169
},
"hi": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.1171519
},
"th": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.11580689999999999
},
"bn": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:45:44.015Z",
"costUsd": 0.1376269
},
"it": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:48:34.035Z",
"costUsd": 0.0875869
},
"da": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:48:34.035Z",
"costUsd": 0.0830469
},
"no": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:48:34.035Z",
"costUsd": 0.08986190000000001
},
"hu": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:48:34.035Z",
"costUsd": 0.0911269
},
"fi": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:48:34.035Z",
"costUsd": 0.09436689999999999
},
"el": {
"hash": "c0eb50d6772b5e61",
"translatedAt": "2025-12-23T00:48:34.035Z",
"costUsd": 0.19731189999999998
}
}
}

309
.agent/services/claude-mem/docs/i18n/README.ar.md Normal file
View File

@@ -0,0 +1,309 @@
<section dir="rtl">
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">أداة إضافية لـ <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> تعمل على أتمتة تسجيل معلومات الجلسات السابقه، وضغطها, ثم حقن السياق ذي الصلة في الجلسات المستقبلية.
</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#بداية-سريعة">بداية سريعة</a> •
<a href="#كيف-يعمل">كيف يعمل</a> •
<a href="#أدوات-البحث-mcp-search-tools">أدوات البحث</a> •
<a href="#المستندات">التوثيق</a> •
<a href="#الإعدادات">الإعدادات</a> •
<a href="#استكشاف-الأخطاء-وإصلاحها">استكشاف الأخطاء وإصلاحها</a> •
<a href="#الترخيص-license">الترخيص</a>
</p>
<p align="center" dir="rtl">
Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة لسياق عمل Claude Code. وظيفته الأساسية هي جعل "كلود" يتذكر ما فعله في جلسات العمل السابقة بسلاسة، عبر تسجيل تحركاته، وإنشاء ملخصات ذكية، واستدعائها في الجلسات المستقبلية. هذا يضمن عدم ضياع سياق المشروع حتى لو أغلقت البرنامج وفتحته لاحقاً.
</p>
---
## بداية سريعة
للبدء، افتح "Claude Code" في مبنى الأوامر (Terminal) واكتب الأوامر التالية:
<div dir="ltr" align="left">
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
</div>
بمجرد إعادة تشغيل Claude Code، سيتم استدعاء السياق من الجلسات السابقة تلقائيا عند الحاجة.
**الميزات الرئيسية:**
- 🧠 **ذاكرة مستديمه**: سياق عملك لا ينتهي بانتهاء الجلسة، بل ينتقل معك للجلسة التالية.
- 📊 **الكشف التدريجي** (Progressive Disclosure): نظام ذكي يستدعي المعلومات على طبقات، مما يمنحك رؤية واضحة لاستهلاك الـ "Tokens" (التكلفة).
- 🔍 **بحث سريع** - استعلم عن سجل مشروعك باستخدام خاصية `mem-search`.
- 🖥️ **واجهة مستخدم ويب** - رؤية معلومات الذاكرة مع تحديث فوري عبر المتصفح من خلال الرابط: http://localhost:37777
- 💻 **تكامل مع Claude Desktop** - إمكانية البحث في الذاكرة مباشرة من واجهة Claude المكتبية
- 🔒 **التحكم في الخصوصية** - دعم وسم `<private>` لمنع النظام من تخزين أي معلومات حساسة.
- ⚙️ **إعدادات السياق** - تحكم دقيق في السياق (context) التي سيتم حقنها في سياق المحادثة.
- 🤖 **أتمتة كاملة:** - النظام يعمل في الخلفية دون الحاجة لتدخل يدوي منك.
- 🔗 **الاستشهادات** - رجوع إلى الملاحظات السابقة باستخدام (http://localhost:37777/api/observation/{id} أو عرض جميع المعلومات على http://localhost:37777)
- 🧪 **مزايا التجريبيه** - تجربة مميزات مثل "الوضع اللانهائي" (Endless Mode).
---
## المستندات
📚 **[عرض التوثيق الكامل](https://docs.claude-mem.ai/)** - تصفح على الموقع الرسمي
### البدء
- **[دليل التثبيت](https://docs.claude-mem.ai/installation)** - البدء السريع والتثبيت المتقدم
- **[دليل الاستخدام](https://docs.claude-mem.ai/usage/getting-started)** - كيف يعمل Claude-Mem تلقائيًا
- **[أدوات البحث](https://docs.claude-mem.ai/usage/search-tools)** - استعلم عن سجل مشروعك بلغتك
- **[الميزات التجريبية](https://docs.claude-mem.ai/beta-features)** - جرّب الميزات التجريبية مثل Endless Mode
### أفضل الممارسات
- **[هندسة السياق](https://docs.claude-mem.ai/context-engineering)** - مبادئ تحسين سياق وكيل الذكاء الاصطناعي
- **[الكشف التدريجي](https://docs.claude-mem.ai/progressive-disclosure)** - الفلسفة وراء استراتيجية تهيئة السياق في Claude-Mem
### البنية المعمارية
- **[نظرة عامة](https://docs.claude-mem.ai/architecture/overview)** - مكونات النظام وتدفق البيانات
- **[تطور البنية المعمارية](https://docs.claude-mem.ai/architecture-evolution)** - تطور المعمارية من v3 إلى v5
- **[بنية برامج الربط (Hooks)](https://docs.claude-mem.ai/hooks-architecture)** - كيف يستخدم Claude-Mem خطافات دورة الحياة
- **[مرجع برامج الربط (Hooks)](https://docs.claude-mem.ai/architecture/hooks)** - شرح 7 سكريبتات خطافات
- **[خدمة العامل](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API وإدارة Bun
- **[قاعدة البيانات](https://docs.claude-mem.ai/architecture/database)** - مخطط SQLite وبحث FTS5
- **[بنية البحث](https://docs.claude-mem.ai/architecture/search-architecture)** - البحث المختلط مع قاعدة بيانات المتجهات Chroma
### الإعدادات والتطوير
- **[الإعدادات](https://docs.claude-mem.ai/configuration)** - متغيرات البيئة والإعدادات
- **[التطوير](https://docs.claude-mem.ai/development)** - البناء، الاختبار، سير العمل للمساهمة
- **[استكشاف الأخطاء وإصلاحها](https://docs.claude-mem.ai/troubleshooting)** - المشكلات الشائعة والحلول
---
## كيف يعمل
**المكونات الأساسية:**
1. **5 برامج ربط (Hooks)** - SessionStart، UserPromptSubmit، PostToolUse، Stop، SessionEnd
2. **تثبيت ذكي** - فاحص التبعيات المخزنة مؤقتًا
3. **خدمة العامل** - HTTP API على المنفذ 37777 مع واجهة مستخدم عارض الويب و10 نقاط نهاية للبحث، تديرها Bun
4. **قاعدة بيانات SQLite** - تخزن الجلسات، الملاحظات، الملخصات
5. **مهارة mem-search** - استعلامات اللغة الطبيعية مع الكشف التدريجي
6. **قاعدة بيانات المتجهات Chroma** - البحث الدلالي الهجين + الكلمات المفتاحية لاسترجاع السياق الذكي
انظر [نظرة عامة على البنية المعمارية](https://docs.claude-mem.ai/architecture/overview) للتفاصيل.
---
## أدوات البحث (MCP Search Tools)
يوفر Claude-Mem بحثًا ذكيًا من خلال مهارة mem-search التي تُستدعى تلقائيًا عندما تسأل عن العمل السابق:
**كيف يعمل:**
- فقط اسأل بشكل طبيعي: *"ماذا فعلنا في الجلسة الأخيرة؟"* أو *"هل أصلحنا هذا الخطأ من قبل؟"*
- يستدعي Claude تلقائيًا خاصية mem-search للعثور على السياق ذي الصلة
**عمليات البحث المتاحة:**
1. **البحث في الملاحظات** - البحث النصي الكامل عبر الملاحظات
2. **البحث في الجلسات** - البحث النصي الكامل عبر ملخصات الجلسات
3. **البحث في المطالبات** - البحث في طلبات المستخدم الخام
4. **حسب المفهوم** - البحث بواسطة وسوم المفهوم (discovery، problem-solution، pattern، إلخ.)
5. **حسب الملف** - البحث عن الملاحظات التي تشير إلى ملفات محددة
6. **حسب النوع** - البحث حسب النوع (decision، bugfix، feature، refactor، discovery، change)
7. **السياق الحديث** - الحصول على سياق الجلسة الأخيرة لمشروع
8. **الجدول الزمني** - الحصول على جدول زمني موحد للسياق حول نقطة زمنية محددة
9. **الجدول الزمني حسب الاستعلام** - البحث عن الملاحظات والحصول على سياق الجدول الزمني حول أفضل تطابق
10. **مساعدة API** - الحصول على توثيق API البحث
**أمثلة على الاستعلامات:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
انظر [دليل أدوات البحث](https://docs.claude-mem.ai/usage/search-tools) لأمثلة مفصلة.
---
## الميزات التجريبية
يقدم Claude-Mem **قناة تجريبية** بميزات تجريبية مثل **Endless Mode** (بنية ذاكرة بيوميمتية للجلسات الممتدة). بدّل بين الإصدارات المستقرة والتجريبية من واجهة مستخدم عارض الويب على http://localhost:37777 ← الإعدادات.
انظر **[توثيق الميزات التجريبية](https://docs.claude-mem.ai/beta-features)** لتفاصيل حول Endless Mode وكيفية تجربته.
---
## متطلبات النظام
- **Node.js**: 18.0.0 أو أعلى
- **Claude Code**: أحدث إصدار مع دعم الإضافات
- **Bun & uv**: (يتم تثبيتهما تلقائياً) لإدارة العمليات والبحث المتجه.
- **SQLite 3**: للتخزين المستمر (مدمج)
---
## الإعدادات
تتم إدارة الإعدادات في `~/.claude-mem/settings.json` (يتم إنشاؤه تلقائيًا بالقيم الافتراضية عند التشغيل الأول). قم بتكوين نموذج الذكاء الاصطناعي، منفذ العامل، دليل البيانات، مستوى السجل، وإعدادات حقن السياق.
انظر **[دليل الإعدادات](https://docs.claude-mem.ai/configuration)** لجميع الإعدادات المتاحة والأمثلة.
---
## التطوير
انظر **[دليل التطوير](https://docs.claude-mem.ai/development)** لتعليمات البناء، الاختبار، وسير عمل المساهمة.
---
## استكشاف الأخطاء وإصلاحها
إذا واجهت مشكلة، اشرحها لـ Claude وسيقوم بتشغيل خاصية troubleshoot لإصلاحها ذاتياً.
انظر **[دليل استكشاف الأخطاء وإصلاحها](https://docs.claude-mem.ai/troubleshooting)** للمشكلات الشائعة والحلول.
---
## تقارير الأخطاء
أنشئ تقارير أخطاء شاملة باستخدام المولّد الآلي:
<div align=left>
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
</div>
## المساهمة
المساهمات مرحب بها! يُرجى:
1. عمل Fork للمشروع (Repository)
2. إنشاء فرع (branch)
3. إجراء التغييرات مع الاختبارات
4. تحديث المستندات عند الحاجه
5. تقديم Pull Request
انظر [دليل التطوير](https://docs.claude-mem.ai/development) لسير عمل المساهمة.
---
## الترخيص (License)
هذا المشروع مرخص بموجب **ترخيص GNU Affero العام الإصدار 3.0** (AGPL-3.0).
حقوق النشر (C) 2025 Alex Newman (@thedotmack). جميع الحقوق محفوظة.
انظر ملف [LICENSE](LICENSE) للتفاصيل الكاملة.
**ماذا يعني هذا:**
- يمكنك استخدام وتعديل وتوزيع هذا البرنامج بحرية
- إذا قمت بتعديل ونشر على خادم شبكة، يجب أن تتيح كود المصدر الخاص بك
- الأعمال المشتقة يجب أن تكون مرخصة أيضًا تحت AGPL-3.0
- لا يوجد ضمان لهذا البرنامج
**ملاحظة حول Ragtime**: دليل `ragtime/` مرخص بشكل منفصل تحت **ترخيص PolyForm Noncommercial 1.0.0**. انظر [ragtime/LICENSE](ragtime/LICENSE) للتفاصيل.
---
## الدعم
- **التوثيق**: [docs/](docs/)
- **المشكلات**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **المستودع**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **المؤلف**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**مبني باستخدام Claude Agent SDK** | **مدعوم بواسطة Claude Code** | **صُنع باستخدام TypeScript**
</section>

304
.agent/services/claude-mem/docs/i18n/README.bn.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 এটি একটি স্বয়ংক্রিয় অনুবাদ। সম্প্রদায়ের সংশোধন স্বাগত জানাই!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center"><a href="https://claude.com/claude-code" target="_blank">Claude Code</a>-এর জন্য নির্মিত স্থায়ী মেমরি কম্প্রেশন সিস্টেম।</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#দ্রুত-শুরু">দ্রুত শুরু</a> •
<a href="#এটি-কীভাবে-কাজ-করে">এটি কীভাবে কাজ করে</a> •
<a href="#অনুসন্ধান-টুল">অনুসন্ধান টুল</a> •
<a href="#ডকুমেন্টেশন">ডকুমেন্টেশন</a> •
<a href="#কনফিগারেশন">কনফিগারেশন</a> •
<a href="#সমস্যা-সমাধান">সমস্যা সমাধান</a> •
<a href="#লাইসেন্স">লাইসেন্স</a>
</p>
<p align="center">
Claude-Mem স্বয়ংক্রিয়ভাবে টুল ব্যবহারের পর্যবেক্ষণ ক্যাপচার করে, সিমান্টিক সারসংক্ষেপ তৈরি করে এবং সেগুলি ভবিষ্যতের সেশনে উপলব্ধ করে সেশন জুড়ে প্রসঙ্গ নির্বিঘ্নে সংরক্ষণ করে। এটি Claude কে সেশন শেষ হওয়ার বা পুনঃসংযোগের পরেও প্রকল্প সম্পর্কে জ্ঞানের ধারাবাহিকতা বজায় রাখতে সক্ষম করে।
</p>
---
## দ্রুত শুরু
টার্মিনালে একটি নতুন Claude Code সেশন শুরু করুন এবং নিম্নলিখিত কমান্ডগুলি প্রবেশ করান:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Claude Code পুনরায় চালু করুন। পূর্ববর্তী সেশনের প্রসঙ্গ স্বয়ংক্রিয়ভাবে নতুন সেশনে উপস্থিত হবে।
**মূল বৈশিষ্ট্যসমূহ:**
- 🧠 **স্থায়ী মেমরি** - প্রসঙ্গ সেশন জুড়ে টিকে থাকে
- 📊 **প্রগতিশীল প্রকাশ** - টোকেন খরচ দৃশ্যমানতা সহ স্তরযুক্ত মেমরি পুনরুদ্ধার
- 🔍 **দক্ষতা-ভিত্তিক অনুসন্ধান** - mem-search skill দিয়ে আপনার প্রকল্পের ইতিহাস অনুসন্ধান করুন
- 🖥️ **ওয়েব ভিউয়ার UI** - http://localhost:37777 এ রিয়েল-টাইম মেমরি স্ট্রিম
- 💻 **Claude Desktop Skill** - Claude Desktop কথোপকথন থেকে মেমরি অনুসন্ধান করুন
- 🔒 **গোপনীয়তা নিয়ন্ত্রণ** - সংবেদনশীল বিষয়বস্তু স্টোরেজ থেকে বাদ দিতে `<private>` ট্যাগ ব্যবহার করুন
- ⚙️ **প্রসঙ্গ কনফিগারেশন** - কোন প্রসঙ্গ ইনজেক্ট করা হবে তার উপর সূক্ষ্ম নিয়ন্ত্রণ
- 🤖 **স্বয়ংক্রিয় অপারেশন** - কোন ম্যানুয়াল হস্তক্ষেপ প্রয়োজন নেই
- 🔗 **উদ্ধৃতি** - ID দিয়ে পূর্ববর্তী পর্যবেক্ষণ রেফারেন্স করুন (http://localhost:37777/api/observation/{id} এর মাধ্যমে অ্যাক্সেস করুন অথবা http://localhost:37777 এ ওয়েব ভিউয়ারে সব দেখুন)
- 🧪 **বিটা চ্যানেল** - ভার্সন পরিবর্তনের মাধ্যমে Endless Mode-এর মতো পরীক্ষামূলক বৈশিষ্ট্য চেষ্টা করুন
---
## ডকুমেন্টেশন
📚 **[সম্পূর্ণ ডকুমেন্টেশন দেখুন](https://docs.claude-mem.ai/)** - অফিসিয়াল ওয়েবসাইটে ব্রাউজ করুন
### শুরু করা
- **[ইনস্টলেশন গাইড](https://docs.claude-mem.ai/installation)** - দ্রুত শুরু এবং উন্নত ইনস্টলেশন
- **[ব্যবহার গাইড](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem কীভাবে স্বয়ংক্রিয়ভাবে কাজ করে
- **[অনুসন্ধান টুল](https://docs.claude-mem.ai/usage/search-tools)** - প্রাকৃতিক ভাষা দিয়ে আপনার প্রকল্পের ইতিহাস অনুসন্ধান করুন
- **[বিটা বৈশিষ্ট্য](https://docs.claude-mem.ai/beta-features)** - Endless Mode-এর মতো পরীক্ষামূলক বৈশিষ্ট্য চেষ্টা করুন
### সর্বোত্তম অনুশীলন
- **[প্রসঙ্গ ইঞ্জিনিয়ারিং](https://docs.claude-mem.ai/context-engineering)** - AI এজেন্ট প্রসঙ্গ অপটিমাইজেশন নীতি
- **[প্রগতিশীল প্রকাশ](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem-এর প্রসঙ্গ প্রাইমিং কৌশলের পিছনে দর্শন
### আর্কিটেকচার
- **[সারসংক্ষেপ](https://docs.claude-mem.ai/architecture/overview)** - সিস্টেম উপাদান এবং ডেটা ফ্লো
- **[আর্কিটেকচার বিবর্তন](https://docs.claude-mem.ai/architecture-evolution)** - v3 থেকে v5 পর্যন্ত যাত্রা
- **[হুকস আর্কিটেকচার](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem কীভাবে লাইফসাইকেল হুক ব্যবহার করে
- **[হুকস রেফারেন্স](https://docs.claude-mem.ai/architecture/hooks)** - ৭টি হুক স্ক্রিপ্ট ব্যাখ্যা করা হয়েছে
- **[ওয়ার্কার সার্ভিস](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API এবং Bun ম্যানেজমেন্ট
- **[ডাটাবেস](https://docs.claude-mem.ai/architecture/database)** - SQLite স্কিমা এবং FTS5 অনুসন্ধান
- **[অনুসন্ধান আর্কিটেকচার](https://docs.claude-mem.ai/architecture/search-architecture)** - Chroma ভেক্টর ডাটাবেস সহ হাইব্রিড অনুসন্ধান
### কনফিগারেশন এবং ডেভেলপমেন্ট
- **[কনফিগারেশন](https://docs.claude-mem.ai/configuration)** - পরিবেশ ভেরিয়েবল এবং সেটিংস
- **[ডেভেলপমেন্ট](https://docs.claude-mem.ai/development)** - বিল্ডিং, টেস্টিং, অবদান
- **[সমস্যা সমাধান](https://docs.claude-mem.ai/troubleshooting)** - সাধারণ সমস্যা এবং সমাধান
---
## এটি কীভাবে কাজ করে
**মূল উপাদানসমূহ:**
1. **৫টি লাইফসাইকেল হুক** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (৬টি হুক স্ক্রিপ্ট)
2. **স্মার্ট ইনস্টল** - ক্যাশড ডিপেন্ডেন্সি চেকার (প্রি-হুক স্ক্রিপ্ট, লাইফসাইকেল হুক নয়)
3. **ওয়ার্কার সার্ভিস** - ওয়েব ভিউয়ার UI এবং ১০টি অনুসন্ধান এন্ডপয়েন্ট সহ পোর্ট 37777-এ HTTP API, Bun দ্বারা পরিচালিত
4. **SQLite ডাটাবেস** - সেশন, পর্যবেক্ষণ, সারসংক্ষেপ সংরক্ষণ করে
5. **mem-search Skill** - প্রগতিশীল প্রকাশ সহ প্রাকৃতিক ভাষা প্রশ্ন
6. **Chroma ভেক্টর ডাটাবেস** - বুদ্ধিমান প্রসঙ্গ পুনরুদ্ধারের জন্য হাইব্রিড সিমান্টিক + কীওয়ার্ড অনুসন্ধান
বিস্তারিত জানতে [আর্কিটেকচার সারসংক্ষেপ](https://docs.claude-mem.ai/architecture/overview) দেখুন।
---
## অনুসন্ধান টুল
Claude-Mem, mem-search skill-এর মাধ্যমে বুদ্ধিমান অনুসন্ধান প্রদান করে যা আপনি পূর্ববর্তী কাজ সম্পর্কে জিজ্ঞাসা করলে স্বয়ংক্রিয়ভাবে চালু হয়:
**এটি কীভাবে কাজ করে:**
- শুধু স্বাভাবিকভাবে জিজ্ঞাসা করুন: *"গত সেশনে আমরা কী করেছিলাম?"* অথবা *"আমরা কি আগে এই বাগটি ঠিক করেছিলাম?"*
- Claude স্বয়ংক্রিয়ভাবে প্রাসঙ্গিক প্রসঙ্গ খুঁজে পেতে mem-search skill চালু করে
**উপলব্ধ অনুসন্ধান অপারেশনসমূহ:**
1. **অবজারভেশন অনুসন্ধান করুন** - পর্যবেক্ষণ জুড়ে পূর্ণ-পাঠ্য অনুসন্ধান
2. **সেশন অনুসন্ধান করুন** - সেশন সারসংক্ষেপ জুড়ে পূর্ণ-পাঠ্য অনুসন্ধান
3. **প্রম্পট অনুসন্ধান করুন** - কাঁচা ব্যবহারকারী অনুরোধ অনুসন্ধান করুন
4. **ধারণা অনুযায়ী** - ধারণা ট্যাগ দ্বারা খুঁজুন (discovery, problem-solution, pattern, ইত্যাদি)
5. **ফাইল অনুযায়ী** - নির্দিষ্ট ফাইল উল্লেখ করা পর্যবেক্ষণ খুঁজুন
6. **টাইপ অনুযায়ী** - টাইপ দ্বারা খুঁজুন (decision, bugfix, feature, refactor, discovery, change)
7. **সাম্প্রতিক প্রসঙ্গ** - একটি প্রকল্পের জন্য সাম্প্রতিক সেশন প্রসঙ্গ পান
8. **টাইমলাইন** - সময়ের একটি নির্দিষ্ট বিন্দুর চারপাশে প্রসঙ্গের একীভূত টাইমলাইন পান
9. **প্রশ্ন দ্বারা টাইমলাইন** - পর্যবেক্ষণ অনুসন্ধান করুন এবং সেরা মিলের চারপাশে টাইমলাইন প্রসঙ্গ পান
10. **API সহায়তা** - অনুসন্ধান API ডকুমেন্টেশন পান
**প্রাকৃতিক ভাষা প্রশ্নের উদাহরণ:**
```
"গত সেশনে আমরা কোন বাগ ঠিক করেছিলাম?"
"আমরা কীভাবে অথেন্টিকেশন প্রয়োগ করেছি?"
"worker-service.ts-এ কী পরিবর্তন করা হয়েছিল?"
"এই প্রকল্পে সাম্প্রতিক কাজ দেখান"
"ভিউয়ার UI যোগ করার সময় কী হচ্ছিল?"
```
বিস্তারিত উদাহরণের জন্য [অনুসন্ধান টুল গাইড](https://docs.claude-mem.ai/usage/search-tools) দেখুন।
---
## বিটা বৈশিষ্ট্য
Claude-Mem একটি **বিটা চ্যানেল** অফার করে যাতে **Endless Mode**-এর মতো পরীক্ষামূলক বৈশিষ্ট্য রয়েছে (বর্ধিত সেশনের জন্য বায়োমিমেটিক মেমরি আর্কিটেকচার)। http://localhost:37777 → Settings-এ ওয়েব ভিউয়ার UI থেকে স্থিতিশীল এবং বিটা সংস্করণের মধ্যে স্যুইচ করুন।
Endless Mode এবং এটি কীভাবে চেষ্টা করবেন সে সম্পর্কে বিস্তারিত জানতে **[বিটা বৈশিষ্ট্য ডকুমেন্টেশন](https://docs.claude-mem.ai/beta-features)** দেখুন।
---
## সিস্টেম প্রয়োজনীয়তা
- **Node.js**: 18.0.0 বা উচ্চতর
- **Claude Code**: প্লাগইন সাপোর্ট সহ সর্বশেষ সংস্করণ
- **Bun**: JavaScript রানটাইম এবং প্রসেস ম্যানেজার (অনুপস্থিত থাকলে স্বয়ংক্রিয়ভাবে ইনস্টল হয়)
- **uv**: ভেক্টর অনুসন্ধানের জন্য Python প্যাকেজ ম্যানেজার (অনুপস্থিত থাকলে স্বয়ংক্রিয়ভাবে ইনস্টল হয়)
- **SQLite 3**: স্থায়ী স্টোরেজের জন্য (বান্ডল করা)
---
## কনফিগারেশন
সেটিংস `~/.claude-mem/settings.json`-এ পরিচালিত হয় (প্রথম রানে ডিফল্ট সহ স্বয়ংক্রিয়ভাবে তৈরি হয়)। AI মডেল, ওয়ার্কার পোর্ট, ডেটা ডিরেক্টরি, লগ লেভেল এবং প্রসঙ্গ ইনজেকশন সেটিংস কনফিগার করুন।
সমস্ত উপলব্ধ সেটিংস এবং উদাহরণের জন্য **[কনফিগারেশন গাইড](https://docs.claude-mem.ai/configuration)** দেখুন।
---
## ডেভেলপমেন্ট
বিল্ড নির্দেশাবলী, টেস্টিং এবং অবদান ওয়ার্কফ্লোর জন্য **[ডেভেলপমেন্ট গাইড](https://docs.claude-mem.ai/development)** দেখুন।
---
## সমস্যা সমাধান
যদি সমস্যার সম্মুখীন হন, Claude-কে সমস্যাটি বর্ণনা করুন এবং troubleshoot skill স্বয়ংক্রিয়ভাবে নির্ণয় করবে এবং সমাধান প্রদান করবে।
সাধারণ সমস্যা এবং সমাধানের জন্য **[সমস্যা সমাধান গাইড](https://docs.claude-mem.ai/troubleshooting)** দেখুন।
---
## বাগ রিপোর্ট
স্বয়ংক্রিয় জেনারেটর দিয়ে বিস্তৃত বাগ রিপোর্ট তৈরি করুন:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## অবদান
অবদান স্বাগত জানাই! অনুগ্রহ করে:
1. রিপোজিটরি ফর্ক করুন
2. একটি ফিচার ব্র্যাঞ্চ তৈরি করুন
3. টেস্ট সহ আপনার পরিবর্তনগুলি করুন
4. ডকুমেন্টেশন আপডেট করুন
5. একটি Pull Request জমা দিন
অবদান ওয়ার্কফ্লোর জন্য [ডেভেলপমেন্ট গাইড](https://docs.claude-mem.ai/development) দেখুন।
---
## লাইসেন্স
এই প্রকল্পটি **GNU Affero General Public License v3.0** (AGPL-3.0) এর অধীনে লাইসেন্সপ্রাপ্ত।
Copyright (C) 2025 Alex Newman (@thedotmack). সর্বস্বত্ব সংরক্ষিত।
সম্পূর্ণ বিবরণের জন্য [LICENSE](LICENSE) ফাইল দেখুন।
**এর অর্থ কী:**
- আপনি এই সফটওয়্যারটি অবাধে ব্যবহার, পরিবর্তন এবং বিতরণ করতে পারেন
- যদি আপনি পরিবর্তন করেন এবং একটি নেটওয়ার্ক সার্ভারে ডিপ্লয় করেন, তাহলে আপনাকে আপনার সোর্স কোড উপলব্ধ করতে হবে
- ডেরিভেটিভ কাজগুলিও AGPL-3.0 এর অধীনে লাইসেন্সপ্রাপ্ত হতে হবে
- এই সফটওয়্যারের জন্য কোনও ওয়ারেন্টি নেই
**Ragtime সম্পর্কে নোট**: `ragtime/` ডিরেক্টরি আলাদাভাবে **PolyForm Noncommercial License 1.0.0** এর অধীনে লাইসেন্সপ্রাপ্ত। বিস্তারিত জানতে [ragtime/LICENSE](ragtime/LICENSE) দেখুন।
---
## সাপোর্ট
- **ডকুমেন্টেশন**: [docs/](docs/)
- **ইস্যু**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **রিপোজিটরি**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **লেখক**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDK দিয়ে নির্মিত** | **Claude Code দ্বারা চালিত** | **TypeScript দিয়ে তৈরি**

306
.agent/services/claude-mem/docs/i18n/README.cs.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 Toto je automatický překlad. Komunitní opravy jsou vítány!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Systém trvalé komprese paměti vytvořený pro <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#rychlý-start">Rychlý start</a> •
<a href="#jak-to-funguje">Jak to funguje</a> •
<a href="#vyhledávací-nástroje-mcp">Vyhledávací nástroje</a> •
<a href="#dokumentace">Dokumentace</a> •
<a href="#konfigurace">Konfigurace</a> •
<a href="#řešení-problémů">Řešení problémů</a> •
<a href="#licence">Licence</a>
</p>
<p align="center">
Claude-Mem bezproblémově zachovává kontext napříč sezeními tím, že automaticky zaznamenává pozorování použití nástrojů, generuje sémantické souhrny a zpřístupňuje je budoucím sezením. To umožňuje Claude udržovat kontinuitu znalostí o projektech i po ukončení nebo opětovném připojení sezení.
</p>
---
## Rychlý start
Spusťte nové sezení Claude Code v terminálu a zadejte následující příkazy:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Restartujte Claude Code. Kontext z předchozích sezení se automaticky objeví v nových sezeních.
**Klíčové vlastnosti:**
- 🧠 **Trvalá paměť** - Kontext přetrvává napříč sezeními
- 📊 **Postupné odhalování** - Vrstvené vyhledávání paměti s viditelností nákladů na tokeny
- 🔍 **Vyhledávání založené na dovednostech** - Dotazujte se na historii projektu pomocí dovednosti mem-search
- 🖥️ **Webové uživatelské rozhraní** - Tok paměti v reálném čase na http://localhost:37777
- 💻 **Dovednost pro Claude Desktop** - Vyhledávejte v paměti z konverzací Claude Desktop
- 🔒 **Kontrola soukromí** - Použijte značky `<private>` k vyloučení citlivého obsahu z úložiště
- ⚙️ **Konfigurace kontextu** - Jemně odstupňovaná kontrola nad tím, jaký kontext se vkládá
- 🤖 **Automatický provoz** - Není vyžadován žádný manuální zásah
- 🔗 **Citace** - Odkazujte na minulá pozorování pomocí ID (přístup přes http://localhost:37777/api/observation/{id} nebo zobrazit vše ve webovém prohlížeči na http://localhost:37777)
- 🧪 **Beta kanál** - Vyzkoušejte experimentální funkce jako Endless Mode přepnutím verze
---
## Dokumentace
📚 **[Zobrazit kompletní dokumentaci](https://docs.claude-mem.ai/)** - Procházet na oficiálních stránkách
### Začínáme
- **[Průvodce instalací](https://docs.claude-mem.ai/installation)** - Rychlý start a pokročilá instalace
- **[Průvodce použitím](https://docs.claude-mem.ai/usage/getting-started)** - Jak Claude-Mem funguje automaticky
- **[Vyhledávací nástroje](https://docs.claude-mem.ai/usage/search-tools)** - Dotazujte se na historii projektu pomocí přirozeného jazyka
- **[Beta funkce](https://docs.claude-mem.ai/beta-features)** - Vyzkoušejte experimentální funkce jako Endless Mode
### Osvědčené postupy
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Principy optimalizace kontextu AI agenta
- **[Postupné odhalování](https://docs.claude-mem.ai/progressive-disclosure)** - Filozofie strategie přípravy kontextu Claude-Mem
### Architektura
- **[Přehled](https://docs.claude-mem.ai/architecture/overview)** - Systémové komponenty a tok dat
- **[Evoluce architektury](https://docs.claude-mem.ai/architecture-evolution)** - Cesta z v3 na v5
- **[Architektura háčků](https://docs.claude-mem.ai/hooks-architecture)** - Jak Claude-Mem používá lifecycle hooks
- **[Reference háčků](https://docs.claude-mem.ai/architecture/hooks)** - Vysvětlení 7 hook skriptů
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API a správa Bun
- **[Databáze](https://docs.claude-mem.ai/architecture/database)** - SQLite schéma a FTS5 vyhledávání
- **[Architektura vyhledávání](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybridní vyhledávání s vektorovou databází Chroma
### Konfigurace a vývoj
- **[Konfigurace](https://docs.claude-mem.ai/configuration)** - Proměnné prostředí a nastavení
- **[Vývoj](https://docs.claude-mem.ai/development)** - Sestavení, testování, přispívání
- **[Řešení problémů](https://docs.claude-mem.ai/troubleshooting)** - Běžné problémy a řešení
---
## Jak to funguje
**Hlavní komponenty:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook skriptů)
2. **Chytrá instalace** - Kontrola cachovaných závislostí (pre-hook skript, ne lifecycle hook)
3. **Worker Service** - HTTP API na portu 37777 s webovým prohlížečem a 10 vyhledávacími endpointy, spravováno pomocí Bun
4. **SQLite databáze** - Ukládá sezení, pozorování, souhrny
5. **mem-search dovednost** - Dotazy v přirozeném jazyce s postupným odhalováním
6. **Chroma vektorová databáze** - Hybridní sémantické + klíčové vyhledávání pro inteligentní vyhledávání kontextu
Podrobnosti najdete v [Přehledu architektury](https://docs.claude-mem.ai/architecture/overview).
---
## Dovednost mem-search
Claude-Mem poskytuje inteligentní vyhledávání prostřednictvím dovednosti mem-search, která se automaticky vyvolá, když se ptáte na minulou práci:
**Jak to funguje:**
- Stačí se zeptat přirozeně: *"Co jsme dělali minulé sezení?"* nebo *"Opravovali jsme tuto chybu dříve?"*
- Claude automaticky vyvolá dovednost mem-search k nalezení relevantního kontextu
**Dostupné vyhledávací operace:**
1. **Search Observations** - Fulltextové vyhledávání napříč pozorováními
2. **Search Sessions** - Fulltextové vyhledávání napříč souhrny sezení
3. **Search Prompts** - Vyhledávání surových požadavků uživatelů
4. **By Concept** - Hledání podle koncepčních značek (discovery, problem-solution, pattern, atd.)
5. **By File** - Hledání pozorování odkazujících na konkrétní soubory
6. **By Type** - Hledání podle typu (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Získání nedávného kontextu sezení pro projekt
8. **Timeline** - Získání jednotné časové osy kontextu kolem konkrétního bodu v čase
9. **Timeline by Query** - Vyhledávání pozorování a získání kontextu časové osy kolem nejlepší shody
10. **API Help** - Získání dokumentace k vyhledávacímu API
**Příklady dotazů v přirozeném jazyce:**
```
"Jaké chyby jsme opravili minulé sezení?"
"Jak jsme implementovali autentizaci?"
"Jaké změny byly provedeny v worker-service.ts?"
"Ukaž mi nedávnou práci na tomto projektu"
"Co se dělo, když jsme přidávali viewer UI?"
```
Podrobné příklady najdete v [Průvodci vyhledávacími nástroji](https://docs.claude-mem.ai/usage/search-tools).
---
## Beta funkce
Claude-Mem nabízí **beta kanál** s experimentálními funkcemi jako **Endless Mode** (biomimetická architektura paměti pro prodloužená sezení). Přepínejte mezi stabilní a beta verzí z webového rozhraní na http://localhost:37777 → Settings.
Podrobnosti o Endless Mode a jak jej vyzkoušet najdete v **[Dokumentaci beta funkcí](https://docs.claude-mem.ai/beta-features)**.
---
## Systémové požadavky
- **Node.js**: 18.0.0 nebo vyšší
- **Claude Code**: Nejnovější verze s podporou pluginů
- **Bun**: JavaScript runtime a správce procesů (automaticky nainstalován, pokud chybí)
- **uv**: Python správce balíčků pro vektorové vyhledávání (automaticky nainstalován, pokud chybí)
- **SQLite 3**: Pro trvalé úložiště (součástí balíčku)
---
## Konfigurace
Nastavení jsou spravována v `~/.claude-mem/settings.json` (automaticky vytvořeno s výchozími hodnotami při prvním spuštění). Konfigurujte AI model, port workeru, datový adresář, úroveň logování a nastavení vkládání kontextu.
Všechna dostupná nastavení a příklady najdete v **[Průvodci konfigurací](https://docs.claude-mem.ai/configuration)**.
---
## Vývoj
Podrobné pokyny k sestavení, testování a pracovnímu postupu pro přispívání najdete v **[Průvodci vývojem](https://docs.claude-mem.ai/development)**.
---
## Řešení problémů
Pokud zaznamenáváte problémy, popište problém Claude a dovednost troubleshoot automaticky diagnostikuje a poskytne opravy.
Běžné problémy a řešení najdete v **[Průvodci řešením problémů](https://docs.claude-mem.ai/troubleshooting)**.
---
## Hlášení chyb
Vytvořte komplexní hlášení chyby pomocí automatického generátoru:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Přispívání
Příspěvky jsou vítány! Prosím:
1. Forkněte repositář
2. Vytvořte feature branch
3. Proveďte změny s testy
4. Aktualizujte dokumentaci
5. Odešlete Pull Request
Pracovní postup pro přispívání najdete v [Průvodci vývojem](https://docs.claude-mem.ai/development).
---
## Licence
Tento projekt je licencován pod **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Všechna práva vyhrazena.
Úplné podrobnosti najdete v souboru [LICENSE](LICENSE).
**Co to znamená:**
- Software můžete volně používat, upravovat a distribuovat
- Pokud jej upravíte a nasadíte na síťovém serveru, musíte zpřístupnit svůj zdrojový kód
- Odvozená díla musí být také licencována pod AGPL-3.0
- Pro tento software neexistuje ŽÁDNÁ ZÁRUKA
**Poznámka k Ragtime**: Adresář `ragtime/` je licencován samostatně pod **PolyForm Noncommercial License 1.0.0**. Podrobnosti najdete v [ragtime/LICENSE](ragtime/LICENSE).
---
## Podpora
- **Dokumentace**: [docs/](docs/)
- **Problémy**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositář**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Vytvořeno pomocí Claude Agent SDK** | **Poháněno Claude Code** | **Vyrobeno s TypeScript**
---

304
.agent/services/claude-mem/docs/i18n/README.da.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Dette er en automatisk oversættelse. Fællesskabsrettelser er velkomne!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Vedvarende hukommelseskomprimeringsystem bygget til <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#hurtig-start">Hurtig Start</a> •
<a href="#sådan-virker-det">Sådan Virker Det</a> •
<a href="#søgeværktøjer-via-mcp">Søgeværktøjer</a> •
<a href="#dokumentation">Dokumentation</a> •
<a href="#konfiguration">Konfiguration</a> •
<a href="#fejlfinding">Fejlfinding</a> •
<a href="#licens">Licens</a>
</p>
<p align="center">
Claude-Mem bevarer problemfrit kontekst på tværs af sessioner ved automatisk at fange observationer af værktøjsbrug, generere semantiske resuméer og gøre dem tilgængelige for fremtidige sessioner. Dette gør det muligt for Claude at opretholde kontinuitet i viden om projekter, selv efter sessioner afsluttes eller genopretter forbindelse.
</p>
---
## Hurtig Start
Start en ny Claude Code-session i terminalen og indtast følgende kommandoer:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Genstart Claude Code. Kontekst fra tidligere sessioner vil automatisk vises i nye sessioner.
**Nøglefunktioner:**
- 🧠 **Vedvarende Hukommelse** - Kontekst overlever på tværs af sessioner
- 📊 **Progressiv Afsløring** - Lagdelt hukommelseshentning med synlighed af token-omkostninger
- 🔍 **Færdighedsbaseret Søgning** - Forespørg din projekthistorik med mem-search-færdighed
- 🖥️ **Web Viewer UI** - Realtids hukommelsesstream på http://localhost:37777
- 💻 **Claude Desktop-færdighed** - Søg i hukommelsen fra Claude Desktop-samtaler
- 🔒 **Privatkontrol** - Brug `<private>`-tags til at ekskludere følsomt indhold fra lagring
- ⚙️ **Kontekstkonfiguration** - Finjusteret kontrol over hvilken kontekst der indsprøjtes
- 🤖 **Automatisk Drift** - Ingen manuel indgriben påkrævet
- 🔗 **Citationer** - Henvisning til tidligere observationer med ID'er (tilgås via http://localhost:37777/api/observation/{id} eller se alle i web viewer på http://localhost:37777)
- 🧪 **Beta-kanal** - Prøv eksperimentelle funktioner som Endless Mode via versionsskift
---
## Dokumentation
📚 **[Se Fuld Dokumentation](https://docs.claude-mem.ai/)** - Gennemse på den officielle hjemmeside
### Kom Godt I Gang
- **[Installationsguide](https://docs.claude-mem.ai/installation)** - Hurtig start & avanceret installation
- **[Brugervejledning](https://docs.claude-mem.ai/usage/getting-started)** - Sådan fungerer Claude-Mem automatisk
- **[Søgeværktøjer](https://docs.claude-mem.ai/usage/search-tools)** - Forespørg din projekthistorik med naturligt sprog
- **[Beta-funktioner](https://docs.claude-mem.ai/beta-features)** - Prøv eksperimentelle funktioner som Endless Mode
### Bedste Praksis
- **[Kontekst-engineering](https://docs.claude-mem.ai/context-engineering)** - AI-agent kontekstoptimeringsprincipper
- **[Progressiv Afsløring](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofien bag Claude-Mems kontekst-priming-strategi
### Arkitektur
- **[Oversigt](https://docs.claude-mem.ai/architecture/overview)** - Systemkomponenter & dataflow
- **[Arkitekturudvikling](https://docs.claude-mem.ai/architecture-evolution)** - Rejsen fra v3 til v5
- **[Hooks-arkitektur](https://docs.claude-mem.ai/hooks-architecture)** - Hvordan Claude-Mem bruger livscyklus-hooks
- **[Hooks-reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook-scripts forklaret
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun-administration
- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite-skema & FTS5-søgning
- **[Søgearkitektur](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid søgning med Chroma vektordatabase
### Konfiguration & Udvikling
- **[Konfiguration](https://docs.claude-mem.ai/configuration)** - Miljøvariabler & indstillinger
- **[Udvikling](https://docs.claude-mem.ai/development)** - Bygning, testning, bidrag
- **[Fejlfinding](https://docs.claude-mem.ai/troubleshooting)** - Almindelige problemer & løsninger
---
## Sådan Virker Det
**Kernekomponenter:**
1. **5 Livscyklus-hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook-scripts)
2. **Smart Installation** - Cached dependency checker (pre-hook script, ikke en livscyklus-hook)
3. **Worker Service** - HTTP API på port 37777 med web viewer UI og 10 søge-endpoints, administreret af Bun
4. **SQLite Database** - Gemmer sessioner, observationer, resuméer
5. **mem-search-færdighed** - Naturlige sprogforespørgsler med progressiv afsløring
6. **Chroma Vector Database** - Hybrid semantisk + søgeordssøgning for intelligent konteksthentning
Se [Arkitekturoversigt](https://docs.claude-mem.ai/architecture/overview) for detaljer.
---
## mem-search-færdighed
Claude-Mem leverer intelligent søgning gennem mem-search-færdigheden, der automatisk aktiveres, når du spørger om tidligere arbejde:
**Sådan Virker Det:**
- Spørg bare naturligt: *"Hvad lavede vi sidste session?"* eller *"Har vi løst denne fejl før?"*
- Claude aktiverer automatisk mem-search-færdigheden for at finde relevant kontekst
**Tilgængelige Søgeoperationer:**
1. **Search Observations** - Fuldtekstsøgning på tværs af observationer
2. **Search Sessions** - Fuldtekstsøgning på tværs af sessionsresumeer
3. **Search Prompts** - Søg i rå brugeranmodninger
4. **By Concept** - Find efter koncept-tags (discovery, problem-solution, pattern, osv.)
5. **By File** - Find observationer, der refererer til specifikke filer
6. **By Type** - Find efter type (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Få nylig sessionskontekst for et projekt
8. **Timeline** - Få samlet tidslinje af kontekst omkring et specifikt tidspunkt
9. **Timeline by Query** - Søg efter observationer og få tidslinjekontekst omkring bedste match
10. **API Help** - Få søge-API-dokumentation
**Eksempler på Naturlige Sprogforespørgsler:**
```
"Hvilke fejl løste vi sidste session?"
"Hvordan implementerede vi autentificering?"
"Hvilke ændringer blev lavet i worker-service.ts?"
"Vis mig det seneste arbejde på dette projekt"
"Hvad skete der, da vi tilføjede viewer UI?"
```
Se [Søgeværktøjsguide](https://docs.claude-mem.ai/usage/search-tools) for detaljerede eksempler.
---
## Beta-funktioner
Claude-Mem tilbyder en **beta-kanal** med eksperimentelle funktioner som **Endless Mode** (biomimetisk hukommelsesarkitektur til udvidede sessioner). Skift mellem stabile og beta-versioner fra web viewer UI på http://localhost:37777 → Settings.
Se **[Beta-funktionsdokumentation](https://docs.claude-mem.ai/beta-features)** for detaljer om Endless Mode og hvordan du prøver det.
---
## Systemkrav
- **Node.js**: 18.0.0 eller højere
- **Claude Code**: Seneste version med plugin-support
- **Bun**: JavaScript runtime og procesmanager (auto-installeres, hvis manglende)
- **uv**: Python package manager til vektorsøgning (auto-installeres, hvis manglende)
- **SQLite 3**: Til vedvarende lagring (bundtet)
---
## Konfiguration
Indstillinger administreres i `~/.claude-mem/settings.json` (auto-oprettet med standardindstillinger ved første kørsel). Konfigurer AI-model, worker-port, datakatalog, log-niveau og indstillinger for kontekstindsprøjtning.
Se **[Konfigurationsguide](https://docs.claude-mem.ai/configuration)** for alle tilgængelige indstillinger og eksempler.
---
## Udvikling
Se **[Udviklingsguide](https://docs.claude-mem.ai/development)** for bygningsinstruktioner, testning og bidragsworkflow.
---
## Fejlfinding
Hvis du oplever problemer, beskriv problemet til Claude, og troubleshoot-færdigheden vil automatisk diagnosticere og levere rettelser.
Se **[Fejlfindingsguide](https://docs.claude-mem.ai/troubleshooting)** for almindelige problemer og løsninger.
---
## Fejlrapporter
Opret omfattende fejlrapporter med den automatiserede generator:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Bidrag
Bidrag er velkomne! Venligst:
1. Fork repositoriet
2. Opret en feature-branch
3. Lav dine ændringer med tests
4. Opdater dokumentation
5. Indsend en Pull Request
Se [Udviklingsguide](https://docs.claude-mem.ai/development) for bidragsworkflow.
---
## Licens
Dette projekt er licenseret under **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Alle rettigheder forbeholdes.
Se [LICENSE](LICENSE)-filen for fulde detaljer.
**Hvad Dette Betyder:**
- Du kan bruge, modificere og distribuere denne software frit
- Hvis du modificerer og implementerer på en netværksserver, skal du gøre din kildekode tilgængelig
- Afledte værker skal også licenseres under AGPL-3.0
- Der er INGEN GARANTI for denne software
**Bemærkning om Ragtime**: `ragtime/`-kataloget er licenseret separat under **PolyForm Noncommercial License 1.0.0**. Se [ragtime/LICENSE](ragtime/LICENSE) for detaljer.
---
## Support
- **Dokumentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Forfatter**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Bygget med Claude Agent SDK** | **Drevet af Claude Code** | **Lavet med TypeScript**

304
.agent/services/claude-mem/docs/i18n/README.de.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Dies ist eine automatisierte Übersetzung. Korrekturen aus der Community sind willkommen!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Persistentes Speicherkomprimierungssystem entwickelt für <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#schnellstart">Schnellstart</a> •
<a href="#wie-es-funktioniert">Wie es funktioniert</a> •
<a href="#mcp-suchwerkzeuge">Suchwerkzeuge</a> •
<a href="#dokumentation">Dokumentation</a> •
<a href="#konfiguration">Konfiguration</a> •
<a href="#fehlerbehebung">Fehlerbehebung</a> •
<a href="#lizenz">Lizenz</a>
</p>
<p align="center">
Claude-Mem bewahrt nahtlos Kontext über Sitzungen hinweg, indem es automatisch Beobachtungen zur Tool-Nutzung erfasst, semantische Zusammenfassungen generiert und diese für zukünftige Sitzungen verfügbar macht. Dies ermöglicht es Claude, die Kontinuität des Wissens über Projekte aufrechtzuerhalten, auch nachdem Sitzungen beendet wurden oder die Verbindung wiederhergestellt wird.
</p>
---
## Schnellstart
Starten Sie eine neue Claude Code-Sitzung im Terminal und geben Sie die folgenden Befehle ein:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Starten Sie Claude Code neu. Kontext aus vorherigen Sitzungen wird automatisch in neuen Sitzungen angezeigt.
**Hauptmerkmale:**
- 🧠 **Persistenter Speicher** - Kontext bleibt über Sitzungen hinweg erhalten
- 📊 **Progressive Offenlegung** - Schichtweise Speicherabruf mit Sichtbarkeit der Token-Kosten
- 🔍 **Skill-basierte Suche** - Durchsuchen Sie Ihre Projekthistorie mit dem mem-search Skill
- 🖥️ **Web-Viewer-UI** - Echtzeit-Speicherstream unter http://localhost:37777
- 💻 **Claude Desktop Skill** - Durchsuchen Sie den Speicher aus Claude Desktop-Konversationen
- 🔒 **Datenschutzkontrolle** - Verwenden Sie `<private>`-Tags, um sensible Inhalte von der Speicherung auszuschließen
- ⚙️ **Kontextkonfiguration** - Feinkörnige Kontrolle darüber, welcher Kontext eingefügt wird
- 🤖 **Automatischer Betrieb** - Keine manuelle Intervention erforderlich
- 🔗 **Zitate** - Referenzieren Sie vergangene Beobachtungen mit IDs (Zugriff über http://localhost:37777/api/observation/{id} oder alle im Web-Viewer unter http://localhost:37777 anzeigen)
- 🧪 **Beta-Kanal** - Probieren Sie experimentelle Funktionen wie den Endless Mode durch Versionswechsel aus
---
## Dokumentation
📚 **[Vollständige Dokumentation anzeigen](https://docs.claude-mem.ai/)** - Auf der offiziellen Website durchsuchen
### Erste Schritte
- **[Installationsanleitung](https://docs.claude-mem.ai/installation)** - Schnellstart & erweiterte Installation
- **[Nutzungsanleitung](https://docs.claude-mem.ai/usage/getting-started)** - Wie Claude-Mem automatisch funktioniert
- **[Suchwerkzeuge](https://docs.claude-mem.ai/usage/search-tools)** - Durchsuchen Sie Ihre Projekthistorie mit natürlicher Sprache
- **[Beta-Funktionen](https://docs.claude-mem.ai/beta-features)** - Probieren Sie experimentelle Funktionen wie den Endless Mode
### Best Practices
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Prinzipien der Kontextoptimierung für KI-Agenten
- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophie hinter Claude-Mems Kontext-Priming-Strategie
### Architektur
- **[Übersicht](https://docs.claude-mem.ai/architecture/overview)** - Systemkomponenten & Datenfluss
- **[Architekturentwicklung](https://docs.claude-mem.ai/architecture-evolution)** - Die Reise von v3 zu v5
- **[Hooks-Architektur](https://docs.claude-mem.ai/hooks-architecture)** - Wie Claude-Mem Lifecycle-Hooks verwendet
- **[Hooks-Referenz](https://docs.claude-mem.ai/architecture/hooks)** - 7 Hook-Skripte erklärt
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun-Verwaltung
- **[Datenbank](https://docs.claude-mem.ai/architecture/database)** - SQLite-Schema & FTS5-Suche
- **[Such-Architektur](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybride Suche mit Chroma-Vektordatenbank
### Konfiguration & Entwicklung
- **[Konfiguration](https://docs.claude-mem.ai/configuration)** - Umgebungsvariablen & Einstellungen
- **[Entwicklung](https://docs.claude-mem.ai/development)** - Erstellen, Testen, Beitragen
- **[Fehlerbehebung](https://docs.claude-mem.ai/troubleshooting)** - Häufige Probleme & Lösungen
---
## Wie es funktioniert
**Kernkomponenten:**
1. **5 Lifecycle-Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 Hook-Skripte)
2. **Smart Install** - Gecachter Abhängigkeitsprüfer (Pre-Hook-Skript, kein Lifecycle-Hook)
3. **Worker Service** - HTTP API auf Port 37777 mit Web-Viewer-UI und 10 Such-Endpunkten, verwaltet von Bun
4. **SQLite-Datenbank** - Speichert Sitzungen, Beobachtungen, Zusammenfassungen
5. **mem-search Skill** - Natürlichsprachliche Abfragen mit progressiver Offenlegung
6. **Chroma-Vektordatenbank** - Hybride semantische + Stichwortsuche für intelligenten Kontextabruf
Siehe [Architekturübersicht](https://docs.claude-mem.ai/architecture/overview) für Details.
---
## mem-search Skill
Claude-Mem bietet intelligente Suche durch den mem-search Skill, der sich automatisch aktiviert, wenn Sie nach früheren Arbeiten fragen:
**Wie es funktioniert:**
- Fragen Sie einfach natürlich: *"Was haben wir in der letzten Sitzung gemacht?"* oder *"Haben wir diesen Fehler schon einmal behoben?"*
- Claude aktiviert automatisch den mem-search Skill, um relevanten Kontext zu finden
**Verfügbare Suchoperationen:**
1. **Search Observations** - Volltextsuche über Beobachtungen
2. **Search Sessions** - Volltextsuche über Sitzungszusammenfassungen
3. **Search Prompts** - Durchsuchen von rohen Benutzeranfragen
4. **By Concept** - Suche nach Konzept-Tags (discovery, problem-solution, pattern, etc.)
5. **By File** - Beobachtungen finden, die bestimmte Dateien referenzieren
6. **By Type** - Suche nach Typ (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Aktuellen Sitzungskontext für ein Projekt abrufen
8. **Timeline** - Einheitliche Zeitachse des Kontexts um einen bestimmten Zeitpunkt herum abrufen
9. **Timeline by Query** - Nach Beobachtungen suchen und Zeitachsenkontext um die beste Übereinstimmung herum abrufen
10. **API Help** - Such-API-Dokumentation abrufen
**Beispiele für natürlichsprachliche Abfragen:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Siehe [Suchwerkzeuge-Anleitung](https://docs.claude-mem.ai/usage/search-tools) für detaillierte Beispiele.
---
## Beta-Funktionen
Claude-Mem bietet einen **Beta-Kanal** mit experimentellen Funktionen wie **Endless Mode** (biomimetische Speicherarchitektur für erweiterte Sitzungen). Wechseln Sie zwischen stabilen und Beta-Versionen über die Web-Viewer-UI unter http://localhost:37777 → Settings.
Siehe **[Beta-Funktionen-Dokumentation](https://docs.claude-mem.ai/beta-features)** für Details zum Endless Mode und wie Sie ihn ausprobieren können.
---
## Systemanforderungen
- **Node.js**: 18.0.0 oder höher
- **Claude Code**: Neueste Version mit Plugin-Unterstützung
- **Bun**: JavaScript-Laufzeitumgebung und Prozessmanager (wird automatisch installiert, falls fehlend)
- **uv**: Python-Paketmanager für Vektorsuche (wird automatisch installiert, falls fehlend)
- **SQLite 3**: Für persistente Speicherung (enthalten)
---
## Konfiguration
Einstellungen werden in `~/.claude-mem/settings.json` verwaltet (wird beim ersten Start automatisch mit Standardwerten erstellt). Konfigurieren Sie KI-Modell, Worker-Port, Datenverzeichnis, Log-Level und Kontext-Injektionseinstellungen.
Siehe die **[Konfigurationsanleitung](https://docs.claude-mem.ai/configuration)** für alle verfügbaren Einstellungen und Beispiele.
---
## Entwicklung
Siehe die **[Entwicklungsanleitung](https://docs.claude-mem.ai/development)** für Build-Anweisungen, Tests und Beitrags-Workflow.
---
## Fehlerbehebung
Wenn Sie Probleme haben, beschreiben Sie das Problem Claude und der troubleshoot Skill wird automatisch diagnostizieren und Lösungen bereitstellen.
Siehe die **[Fehlerbehebungsanleitung](https://docs.claude-mem.ai/troubleshooting)** für häufige Probleme und Lösungen.
---
## Fehlerberichte
Erstellen Sie umfassende Fehlerberichte mit dem automatisierten Generator:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Beiträge
Beiträge sind willkommen! Bitte:
1. Forken Sie das Repository
2. Erstellen Sie einen Feature-Branch
3. Nehmen Sie Ihre Änderungen mit Tests vor
4. Aktualisieren Sie die Dokumentation
5. Reichen Sie einen Pull Request ein
Siehe [Entwicklungsanleitung](https://docs.claude-mem.ai/development) für den Beitrags-Workflow.
---
## Lizenz
Dieses Projekt ist unter der **GNU Affero General Public License v3.0** (AGPL-3.0) lizenziert.
Copyright (C) 2025 Alex Newman (@thedotmack). Alle Rechte vorbehalten.
Siehe die [LICENSE](LICENSE)-Datei für vollständige Details.
**Was das bedeutet:**
- Sie können diese Software frei verwenden, modifizieren und verteilen
- Wenn Sie sie modifizieren und auf einem Netzwerkserver bereitstellen, müssen Sie Ihren Quellcode verfügbar machen
- Abgeleitete Werke müssen ebenfalls unter AGPL-3.0 lizenziert werden
- Es gibt KEINE GARANTIE für diese Software
**Hinweis zu Ragtime**: Das `ragtime/`-Verzeichnis ist separat unter der **PolyForm Noncommercial License 1.0.0** lizenziert. Siehe [ragtime/LICENSE](ragtime/LICENSE) für Details.
---
## Support
- **Dokumentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Erstellt mit Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**

304
.agent/services/claude-mem/docs/i18n/README.el.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Αυτή είναι μια αυτοματοποιημένη μετάφραση. Καλώς ορίζονται οι διορθώσεις από την κοινότητα!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Σύστημα συμπίεσης μόνιμης μνήμης κατασκευασμένο για το <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#γρήγορη-εκκίνηση">Γρήγορη Εκκίνηση</a> •
<a href="#πώς-λειτουργεί">Πώς Λειτουργεί</a> •
<a href="#εργαλεία-αναζήτησης-mcp">Εργαλεία Αναζήτησης</a> •
<a href="#τεκμηρίωση">Τεκμηρίωση</a> •
<a href="#διαμόρφωση">Διαμόρφωση</a> •
<a href="#αντιμετώπιση-προβλημάτων">Αντιμετώπιση Προβλημάτων</a> •
<a href="#άδεια-χρήσης">Άδεια Χρήσης</a>
</p>
<p align="center">
Το Claude-Mem διατηρεί απρόσκοπτα το πλαίσιο μεταξύ συνεδριών καταγράφοντας αυτόματα παρατηρήσεις χρήσης εργαλείων, δημιουργώντας σημασιολογικές περιλήψεις και καθιστώντας τες διαθέσιμες σε μελλοντικές συνεδρίες. Αυτό επιτρέπει στο Claude να διατηρεί τη συνέχεια της γνώσης για έργα ακόμη και μετά το τέλος ή την επανασύνδεση συνεδριών.
</p>
---
## Γρήγορη Εκκίνηση
Ξεκινήστε μια νέα συνεδρία Claude Code στο τερματικό και εισάγετε τις ακόλουθες εντολές:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Επανεκκινήστε το Claude Code. Το πλαίσιο από προηγούμενες συνεδρίες θα εμφανιστεί αυτόματα σε νέες συνεδρίες.
**Βασικά Χαρακτηριστικά:**
- 🧠 **Μόνιμη Μνήμη** - Το πλαίσιο διατηρείται μεταξύ συνεδριών
- 📊 **Προοδευτική Αποκάλυψη** - Ανάκτηση μνήμης σε επίπεδα με ορατότητα κόστους tokens
- 🔍 **Αναζήτηση Βασισμένη σε Δεξιότητες** - Ερωτήματα στο ιστορικό του έργου σας με τη δεξιότητα mem-search
- 🖥️ **Διεπαφή Web Viewer** - Ροή μνήμης σε πραγματικό χρόνο στο http://localhost:37777
- 💻 **Δεξιότητα Claude Desktop** - Αναζήτηση μνήμης από συνομιλίες Claude Desktop
- 🔒 **Έλεγχος Απορρήτου** - Χρησιμοποιήστε ετικέτες `<private>` για να εξαιρέσετε ευαίσθητο περιεχόμενο από την αποθήκευση
- ⚙️ **Διαμόρφωση Πλαισίου** - Λεπτομερής έλεγχος για το ποιο πλαίσιο εισάγεται
- 🤖 **Αυτόματη Λειτουργία** - Δεν απαιτείται χειροκίνητη παρέμβαση
- 🔗 **Αναφορές** - Αναφορά σε παλαιότερες παρατηρήσεις με IDs (πρόσβαση μέσω http://localhost:37777/api/observation/{id} ή προβολή όλων στο web viewer στο http://localhost:37777)
- 🧪 **Κανάλι Beta** - Δοκιμάστε πειραματικά χαρακτηριστικά όπως το Endless Mode μέσω εναλλαγής έκδοσης
---
## Τεκμηρίωση
📚 **[Προβολή Πλήρους Τεκμηρίωσης](https://docs.claude-mem.ai/)** - Περιήγηση στον επίσημο ιστότοπο
### Ξεκινώντας
- **[Οδηγός Εγκατάστασης](https://docs.claude-mem.ai/installation)** - Γρήγορη εκκίνηση & προηγμένη εγκατάσταση
- **[Οδηγός Χρήσης](https://docs.claude-mem.ai/usage/getting-started)** - Πώς λειτουργεί αυτόματα το Claude-Mem
- **[Εργαλεία Αναζήτησης](https://docs.claude-mem.ai/usage/search-tools)** - Ερωτήματα στο ιστορικό του έργου σας με φυσική γλώσσα
- **[Χαρακτηριστικά Beta](https://docs.claude-mem.ai/beta-features)** - Δοκιμάστε πειραματικά χαρακτηριστικά όπως το Endless Mode
### Βέλτιστες Πρακτικές
- **[Μηχανική Πλαισίου](https://docs.claude-mem.ai/context-engineering)** - Αρχές βελτιστοποίησης πλαισίου για AI agents
- **[Προοδευτική Αποκάλυψη](https://docs.claude-mem.ai/progressive-disclosure)** - Φιλοσοφία πίσω από τη στρατηγική προετοιμασίας πλαισίου του Claude-Mem
### Αρχιτεκτονική
- **[Επισκόπηση](https://docs.claude-mem.ai/architecture/overview)** - Συστατικά στοιχεία συστήματος & ροή δεδομένων
- **[Εξέλιξη Αρχιτεκτονικής](https://docs.claude-mem.ai/architecture-evolution)** - Το ταξίδι από το v3 στο v5
- **[Αρχιτεκτονική Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Πώς το Claude-Mem χρησιμοποιεί lifecycle hooks
- **[Αναφορά Hooks](https://docs.claude-mem.ai/architecture/hooks)** - Επεξήγηση 7 hook scripts
- **[Υπηρεσία Worker](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & διαχείριση Bun
- **[Βάση Δεδομένων](https://docs.claude-mem.ai/architecture/database)** - Σχήμα SQLite & αναζήτηση FTS5
- **[Αρχιτεκτονική Αναζήτησης](https://docs.claude-mem.ai/architecture/search-architecture)** - Υβριδική αναζήτηση με βάση δεδομένων διανυσμάτων Chroma
### Διαμόρφωση & Ανάπτυξη
- **[Διαμόρφωση](https://docs.claude-mem.ai/configuration)** - Μεταβλητές περιβάλλοντος & ρυθμίσεις
- **[Ανάπτυξη](https://docs.claude-mem.ai/development)** - Κατασκευή, δοκιμή, συνεισφορά
- **[Αντιμετώπιση Προβλημάτων](https://docs.claude-mem.ai/troubleshooting)** - Συνήθη προβλήματα & λύσεις
---
## Πώς Λειτουργεί
**Βασικά Συστατικά:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. **Έξυπνη Εγκατάσταση** - Έλεγχος εξαρτήσεων με cache (pre-hook script, όχι lifecycle hook)
3. **Υπηρεσία Worker** - HTTP API στη θύρα 37777 με διεπαφή web viewer και 10 endpoints αναζήτησης, διαχειριζόμενη από το Bun
4. **Βάση Δεδομένων SQLite** - Αποθηκεύει συνεδρίες, παρατηρήσεις, περιλήψεις
5. **Δεξιότητα mem-search** - Ερωτήματα φυσικής γλώσσας με προοδευτική αποκάλυψη
6. **Βάση Δεδομένων Διανυσμάτων Chroma** - Υβριδική σημασιολογική + αναζήτηση λέξεων-κλειδιών για έξυπνη ανάκτηση πλαισίου
Δείτε [Επισκόπηση Αρχιτεκτονικής](https://docs.claude-mem.ai/architecture/overview) για λεπτομέρειες.
---
## Δεξιότητα mem-search
Το Claude-Mem παρέχει έξυπνη αναζήτηση μέσω της δεξιότητας mem-search που ενεργοποιείται αυτόματα όταν ρωτάτε για παλαιότερη εργασία:
**Πώς Λειτουργεί:**
- Απλά ρωτήστε φυσικά: *"Τι κάναμε την προηγούμενη συνεδρία;"* ή *"Διορθώσαμε αυτό το σφάλμα νωρίτερα;"*
- Το Claude ενεργοποιεί αυτόματα τη δεξιότητα mem-search για να βρει σχετικό πλαίσιο
**Διαθέσιμες Λειτουργίες Αναζήτησης:**
1. **Search Observations** - Αναζήτηση πλήρους κειμένου σε παρατηρήσεις
2. **Search Sessions** - Αναζήτηση πλήρους κειμένου σε περιλήψεις συνεδριών
3. **Search Prompts** - Αναζήτηση ακατέργαστων αιτημάτων χρήστη
4. **By Concept** - Εύρεση βάσει ετικετών εννοιών (discovery, problem-solution, pattern, κ.λπ.)
5. **By File** - Εύρεση παρατηρήσεων που αναφέρονται σε συγκεκριμένα αρχεία
6. **By Type** - Εύρεση βάσει τύπου (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Λήψη πρόσφατου πλαισίου συνεδρίας για ένα έργο
8. **Timeline** - Λήψη ενοποιημένης χρονολογικής γραμμής πλαισίου γύρω από συγκεκριμένο χρονικό σημείο
9. **Timeline by Query** - Αναζήτηση παρατηρήσεων και λήψη πλαισίου χρονολογικής γραμμής γύρω από την καλύτερη αντιστοιχία
10. **API Help** - Λήψη τεκμηρίωσης API αναζήτησης
**Παραδείγματα Ερωτημάτων Φυσικής Γλώσσας:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Δείτε [Οδηγό Εργαλείων Αναζήτησης](https://docs.claude-mem.ai/usage/search-tools) για λεπτομερή παραδείγματα.
---
## Χαρακτηριστικά Beta
Το Claude-Mem προσφέρει ένα **κανάλι beta** με πειραματικά χαρακτηριστικά όπως το **Endless Mode** (βιομιμητική αρχιτεκτονική μνήμης για εκτεταμένες συνεδρίες). Εναλλαγή μεταξύ σταθερών και beta εκδόσεων από τη διεπαφή web viewer στο http://localhost:37777 → Settings.
Δείτε **[Τεκμηρίωση Χαρακτηριστικών Beta](https://docs.claude-mem.ai/beta-features)** για λεπτομέρειες σχετικά με το Endless Mode και πώς να το δοκιμάσετε.
---
## Απαιτήσεις Συστήματος
- **Node.js**: 18.0.0 ή νεότερο
- **Claude Code**: Τελευταία έκδοση με υποστήριξη plugin
- **Bun**: JavaScript runtime και διαχειριστής διεργασιών (εγκαθίσταται αυτόματα αν λείπει)
- **uv**: Διαχειριστής πακέτων Python για αναζήτηση διανυσμάτων (εγκαθίσταται αυτόματα αν λείπει)
- **SQLite 3**: Για μόνιμη αποθήκευση (συμπεριλαμβάνεται)
---
## Διαμόρφωση
Οι ρυθμίσεις διαχειρίζονται στο `~/.claude-mem/settings.json` (δημιουργείται αυτόματα με προεπιλογές κατά την πρώτη εκτέλεση). Διαμορφώστε το μοντέλο AI, τη θύρα worker, τον κατάλογο δεδομένων, το επίπεδο καταγραφής και τις ρυθμίσεις εισαγωγής πλαισίου.
Δείτε τον **[Οδηγό Διαμόρφωσης](https://docs.claude-mem.ai/configuration)** για όλες τις διαθέσιμες ρυθμίσεις και παραδείγματα.
---
## Ανάπτυξη
Δείτε τον **[Οδηγό Ανάπτυξης](https://docs.claude-mem.ai/development)** για οδηγίες κατασκευής, δοκιμών και ροής εργασίας συνεισφοράς.
---
## Αντιμετώπιση Προβλημάτων
Εάν αντιμετωπίζετε προβλήματα, περιγράψτε το πρόβλημα στο Claude και η δεξιότητα troubleshoot θα διαγνώσει αυτόματα και θα παράσχει λύσεις.
Δείτε τον **[Οδηγό Αντιμετώπισης Προβλημάτων](https://docs.claude-mem.ai/troubleshooting)** για συνήθη προβλήματα και λύσεις.
---
## Αναφορές Σφαλμάτων
Δημιουργήστε περιεκτικές αναφορές σφαλμάτων με την αυτοματοποιημένη γεννήτρια:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Συνεισφορά
Οι συνεισφορές είναι ευπρόσδεκτες! Παρακαλώ:
1. Κάντε Fork το repository
2. Δημιουργήστε ένα feature branch
3. Κάντε τις αλλαγές σας με δοκιμές
4. Ενημερώστε την τεκμηρίωση
5. Υποβάλετε ένα Pull Request
Δείτε τον [Οδηγό Ανάπτυξης](https://docs.claude-mem.ai/development) για τη ροή εργασίας συνεισφοράς.
---
## Άδεια Χρήσης
Αυτό το έργο διατίθεται με άδεια **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Με επιφύλαξη παντός δικαιώματος.
Δείτε το αρχείο [LICENSE](LICENSE) για πλήρεις λεπτομέρειες.
**Τι Σημαίνει Αυτό:**
- Μπορείτε να χρησιμοποιήσετε, να τροποποιήσετε και να διανείμετε ελεύθερα αυτό το λογισμικό
- Εάν τροποποιήσετε και αναπτύξετε σε διακομιστή δικτύου, πρέπει να καταστήσετε διαθέσιμο τον πηγαίο κώδικά σας
- Τα παράγωγα έργα πρέπει επίσης να διατίθενται με άδεια AGPL-3.0
- ΔΕΝ υπάρχει ΕΓΓΥΗΣΗ για αυτό το λογισμικό
**Σημείωση για το Ragtime**: Ο κατάλογος `ragtime/` διατίθεται χωριστά με άδεια **PolyForm Noncommercial License 1.0.0**. Δείτε το [ragtime/LICENSE](ragtime/LICENSE) για λεπτομέρειες.
---
## Υποστήριξη
- **Τεκμηρίωση**: [docs/](docs/)
- **Ζητήματα**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Συγγραφέας**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Κατασκευασμένο με Claude Agent SDK** | **Τροφοδοτείται από Claude Code** | **Φτιαγμένο με TypeScript**

305
.agent/services/claude-mem/docs/i18n/README.es.md Normal file
View File

@@ -0,0 +1,305 @@
🌐 Esta es una traducción automática. ¡Las correcciones de la comunidad son bienvenidas!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistema de compresión de memoria persistente construido para <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#inicio-rápido">Inicio Rápido</a> •
<a href="#cómo-funciona">Cómo Funciona</a> •
<a href="#herramientas-de-búsqueda-mcp">Herramientas de Búsqueda</a> •
<a href="#documentación">Documentación</a> •
<a href="#configuración">Configuración</a> •
<a href="#solución-de-problemas">Solución de Problemas</a> •
<a href="#licencia">Licencia</a>
</p>
<p align="center">
Claude-Mem preserva el contexto sin interrupciones entre sesiones al capturar automáticamente observaciones de uso de herramientas, generar resúmenes semánticos y ponerlos a disposición de sesiones futuras. Esto permite a Claude mantener la continuidad del conocimiento sobre proyectos incluso después de que las sesiones terminen o se reconecten.
</p>
---
## Inicio Rápido
Inicia una nueva sesión de Claude Code en la terminal e ingresa los siguientes comandos:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Reinicia Claude Code. El contexto de sesiones anteriores aparecerá automáticamente en nuevas sesiones.
**Características Principales:**
- 🧠 **Memoria Persistente** - El contexto sobrevive entre sesiones
- 📊 **Divulgación Progresiva** - Recuperación de memoria en capas con visibilidad del costo de tokens
- 🔍 **Búsqueda Basada en Habilidades** - Consulta el historial de tu proyecto con la habilidad mem-search
- 🖥️ **Interfaz de Visor Web** - Transmisión de memoria en tiempo real en http://localhost:37777
- 💻 **Habilidad para Claude Desktop** - Busca en la memoria desde conversaciones de Claude Desktop
- 🔒 **Control de Privacidad** - Usa etiquetas `<private>` para excluir contenido sensible del almacenamiento
- ⚙️ **Configuración de Contexto** - Control detallado sobre qué contexto se inyecta
- 🤖 **Operación Automática** - No se requiere intervención manual
- 🔗 **Citas** - Referencias a observaciones pasadas con IDs (accede vía http://localhost:37777/api/observation/{id} o visualiza todas en el visor web en http://localhost:37777)
- 🧪 **Canal Beta** - Prueba características experimentales como Endless Mode mediante cambio de versión
---
## Documentación
📚 **[Ver Documentación Completa](https://docs.claude-mem.ai/)** - Navegar en el sitio web oficial
### Primeros Pasos
- **[Guía de Instalación](https://docs.claude-mem.ai/installation)** - Inicio rápido e instalación avanzada
- **[Guía de Uso](https://docs.claude-mem.ai/usage/getting-started)** - Cómo funciona Claude-Mem automáticamente
- **[Herramientas de Búsqueda](https://docs.claude-mem.ai/usage/search-tools)** - Consulta el historial de tu proyecto con lenguaje natural
- **[Características Beta](https://docs.claude-mem.ai/beta-features)** - Prueba características experimentales como Endless Mode
### Mejores Prácticas
- **[Ingeniería de Contexto](https://docs.claude-mem.ai/context-engineering)** - Principios de optimización de contexto para agentes de IA
- **[Divulgación Progresiva](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofía detrás de la estrategia de preparación de contexto de Claude-Mem
### Arquitectura
- **[Descripción General](https://docs.claude-mem.ai/architecture/overview)** - Componentes del sistema y flujo de datos
- **[Evolución de la Arquitectura](https://docs.claude-mem.ai/architecture-evolution)** - El viaje de v3 a v5
- **[Arquitectura de Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Cómo Claude-Mem usa hooks de ciclo de vida
- **[Referencia de Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 scripts de hooks explicados
- **[Servicio Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP y gestión de Bun
- **[Base de Datos](https://docs.claude-mem.ai/architecture/database)** - Esquema SQLite y búsqueda FTS5
- **[Arquitectura de Búsqueda](https://docs.claude-mem.ai/architecture/search-architecture)** - Búsqueda híbrida con base de datos vectorial Chroma
### Configuración y Desarrollo
- **[Configuración](https://docs.claude-mem.ai/configuration)** - Variables de entorno y ajustes
- **[Desarrollo](https://docs.claude-mem.ai/development)** - Compilación, pruebas y contribución
- **[Solución de Problemas](https://docs.claude-mem.ai/troubleshooting)** - Problemas comunes y soluciones
---
## Cómo Funciona
**Componentes Principales:**
1. **5 Hooks de Ciclo de Vida** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripts de hooks)
2. **Instalación Inteligente** - Verificador de dependencias en caché (script pre-hook, no un hook de ciclo de vida)
3. **Servicio Worker** - API HTTP en el puerto 37777 con interfaz de visor web y 10 endpoints de búsqueda, gestionado por Bun
4. **Base de Datos SQLite** - Almacena sesiones, observaciones, resúmenes
5. **Habilidad mem-search** - Consultas en lenguaje natural con divulgación progresiva
6. **Base de Datos Vectorial Chroma** - Búsqueda híbrida semántica + palabras clave para recuperación inteligente de contexto
Ver [Descripción General de la Arquitectura](https://docs.claude-mem.ai/architecture/overview) para más detalles.
---
## Habilidad mem-search
Claude-Mem proporciona búsqueda inteligente a través de la habilidad mem-search que se invoca automáticamente cuando preguntas sobre trabajo previo:
**Cómo Funciona:**
- Simplemente pregunta naturalmente: *"¿Qué hicimos en la última sesión?"* o *"¿Arreglamos este error antes?"*
- Claude invoca automáticamente la habilidad mem-search para encontrar contexto relevante
**Operaciones de Búsqueda Disponibles:**
1. **Search Observations** - Búsqueda de texto completo en observaciones
2. **Search Sessions** - Búsqueda de texto completo en resúmenes de sesiones
3. **Search Prompts** - Búsqueda de solicitudes de usuario sin procesar
4. **By Concept** - Buscar por etiquetas de concepto (discovery, problem-solution, pattern, etc.)
5. **By File** - Buscar observaciones que referencian archivos específicos
6. **By Type** - Buscar por tipo (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Obtener contexto de sesión reciente para un proyecto
8. **Timeline** - Obtener línea de tiempo unificada de contexto alrededor de un punto específico en el tiempo
9. **Timeline by Query** - Buscar observaciones y obtener contexto de línea de tiempo alrededor de la mejor coincidencia
10. **API Help** - Obtener documentación de la API de búsqueda
**Ejemplos de Consultas en Lenguaje Natural:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Ver [Guía de Herramientas de Búsqueda](https://docs.claude-mem.ai/usage/search-tools) para ejemplos detallados.
---
## Características Beta
Claude-Mem ofrece un **canal beta** con características experimentales como **Endless Mode** (arquitectura de memoria biomimética para sesiones extendidas). Cambia entre versiones estables y beta desde la interfaz del visor web en http://localhost:37777 → Settings.
Ver **[Documentación de Características Beta](https://docs.claude-mem.ai/beta-features)** para detalles sobre Endless Mode y cómo probarlo.
---
## Requisitos del Sistema
- **Node.js**: 18.0.0 o superior
- **Claude Code**: Última versión con soporte de plugins
- **Bun**: Runtime de JavaScript y gestor de procesos (se instala automáticamente si falta)
- **uv**: Gestor de paquetes de Python para búsqueda vectorial (se instala automáticamente si falta)
- **SQLite 3**: Para almacenamiento persistente (incluido)
---
## Configuración
Los ajustes se gestionan en `~/.claude-mem/settings.json` (se crea automáticamente con valores predeterminados en la primera ejecución). Configura el modelo de IA, puerto del worker, directorio de datos, nivel de registro y ajustes de inyección de contexto.
Ver la **[Guía de Configuración](https://docs.claude-mem.ai/configuration)** para todos los ajustes disponibles y ejemplos.
---
## Desarrollo
Ver la **[Guía de Desarrollo](https://docs.claude-mem.ai/development)** para instrucciones de compilación, pruebas y flujo de contribución.
---
## Solución de Problemas
Si experimentas problemas, describe el problema a Claude y la habilidad troubleshoot diagnosticará automáticamente y proporcionará soluciones.
Ver la **[Guía de Solución de Problemas](https://docs.claude-mem.ai/troubleshooting)** para problemas comunes y soluciones.
---
## Reportes de Errores
Crea reportes de errores completos con el generador automático:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contribuciones
¡Las contribuciones son bienvenidas! Por favor:
1. Haz fork del repositorio
2. Crea una rama de característica
3. Realiza tus cambios con pruebas
4. Actualiza la documentación
5. Envía un Pull Request
Ver [Guía de Desarrollo](https://docs.claude-mem.ai/development) para el flujo de contribución.
---
## Licencia
Este proyecto está licenciado bajo la **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Todos los derechos reservados.
Ver el archivo [LICENSE](LICENSE) para detalles completos.
**Lo Que Esto Significa:**
- Puedes usar, modificar y distribuir este software libremente
- Si modificas y despliegas en un servidor de red, debes hacer tu código fuente disponible
- Los trabajos derivados también deben estar licenciados bajo AGPL-3.0
- NO hay GARANTÍA para este software
**Nota sobre Ragtime**: El directorio `ragtime/` está licenciado por separado bajo la **PolyForm Noncommercial License 1.0.0**. Ver [ragtime/LICENSE](ragtime/LICENSE) para detalles.
---
## Soporte
- **Documentación**: [docs/](docs/)
- **Problemas**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositorio**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Construido con Claude Agent SDK** | **Impulsado por Claude Code** | **Hecho con TypeScript**

303
.agent/services/claude-mem/docs/i18n/README.fi.md Normal file
View File

@@ -0,0 +1,303 @@
🌐 Tämä on automaattinen käännös. Yhteisön korjaukset ovat tervetulleita!
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Pysyvä muistinpakkaamisjärjestelmä, joka on rakennettu <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> -ympäristöön.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#pikaopas">Pikaopas</a> •
<a href="#miten-se-toimii">Miten se toimii</a> •
<a href="#hakutyökalut">Hakutyökalut</a> •
<a href="#dokumentaatio">Dokumentaatio</a> •
<a href="#asetukset">Asetukset</a> •
<a href="#vianmääritys">Vianmääritys</a> •
<a href="#lisenssi">Lisenssi</a>
</p>
<p align="center">
Claude-Mem säilyttää kontekstin saumattomasti istuntojen välillä tallentamalla automaattisesti työkalujen käyttöhavaintoja, luomalla semanttisia yhteenvetoja ja asettamalla ne tulevien istuntojen saataville. Tämä mahdollistaa Clauden säilyttää tiedon jatkuvuuden projekteista senkin jälkeen, kun istunnot päättyvät tai yhteys palautuu.
</p>
---
## Pikaopas
Aloita uusi Claude Code -istunto terminaalissa ja syötä seuraavat komennot:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Käynnistä Claude Code uudelleen. Aiempien istuntojen konteksti ilmestyy automaattisesti uusiin istuntoihin.
**Keskeiset ominaisuudet:**
- 🧠 **Pysyvä muisti** - Konteksti säilyy istuntojen välillä
- 📊 **Asteittainen paljastaminen** - Kerrostettu muistin haku tokenikustannusten näkyvyydellä
- 🔍 **Taitopohjainen haku** - Kysy projektihistoriaasi mem-search-taidolla
- 🖥️ **Web-katselukäyttöliittymä** - Reaaliaikainen muistivirta osoitteessa http://localhost:37777
- 💻 **Claude Desktop -taito** - Hae muistista Claude Desktop -keskusteluissa
- 🔒 **Yksityisyyden hallinta** - Käytä `<private>`-tageja arkaluonteisen sisällön poissulkemiseen tallennuksesta
- ⚙️ **Kontekstin määrittely** - Tarkka hallinta siitä, mikä konteksti injektoidaan
- 🤖 **Automaattinen toiminta** - Ei vaadi manuaalista puuttumista
- 🔗 **Viittaukset** - Viittaa aiempiin havaintoihin ID:llä (käytettävissä osoitteessa http://localhost:37777/api/observation/{id} tai näytä kaikki web-katselussa osoitteessa http://localhost:37777)
- 🧪 **Beta-kanava** - Kokeile kokeellisia ominaisuuksia kuten Endless Mode versionvaihdolla
---
## Dokumentaatio
📚 **[Näytä täydellinen dokumentaatio](https://docs.claude-mem.ai/)** - Selaa virallisella verkkosivustolla
### Aloitus
- **[Asennusopas](https://docs.claude-mem.ai/installation)** - Pikaopas ja edistynyt asennus
- **[Käyttöopas](https://docs.claude-mem.ai/usage/getting-started)** - Miten Claude-Mem toimii automaattisesti
- **[Hakutyökalut](https://docs.claude-mem.ai/usage/search-tools)** - Kysy projektihistoriaasi luonnollisella kielellä
- **[Beta-ominaisuudet](https://docs.claude-mem.ai/beta-features)** - Kokeile kokeellisia ominaisuuksia kuten Endless Mode
### Parhaat käytännöt
- **[Kontekstisuunnittelu](https://docs.claude-mem.ai/context-engineering)** - AI-agentin kontekstin optimointiperiaatteet
- **[Asteittainen paljastaminen](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia Claude-Mem-kontekstin valmistelustrategian takana
### Arkkitehtuuri
- **[Yleiskatsaus](https://docs.claude-mem.ai/architecture/overview)** - Järjestelmän komponentit ja datavirta
- **[Arkkitehtuurin kehitys](https://docs.claude-mem.ai/architecture-evolution)** - Matka versiosta v3 versioon v5
- **[Koukku-arkkitehtuuri](https://docs.claude-mem.ai/hooks-architecture)** - Miten Claude-Mem käyttää elinkaarikkoukkuja
- **[Koukku-viittaus](https://docs.claude-mem.ai/architecture/hooks)** - 7 koukku-skriptiä selitettynä
- **[Worker-palvelu](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API ja Bun-hallinta
- **[Tietokanta](https://docs.claude-mem.ai/architecture/database)** - SQLite-skeema ja FTS5-haku
- **[Hakuarkkitehtuuri](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybridihaku Chroma-vektoritietokannalla
### Asetukset ja kehitys
- **[Asetukset](https://docs.claude-mem.ai/configuration)** - Ympäristömuuttujat ja asetukset
- **[Kehitys](https://docs.claude-mem.ai/development)** - Rakentaminen, testaus, osallistuminen
- **[Vianmääritys](https://docs.claude-mem.ai/troubleshooting)** - Yleiset ongelmat ja ratkaisut
---
## Miten se toimii
**Keskeiset komponentit:**
1. **5 elinkaarikoukua** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 koukku-skriptiä)
2. **Älykäs asennus** - Välimuistettu riippuvuuksien tarkistaja (esikoukku-skripti, ei elinkaarikkoukku)
3. **Worker-palvelu** - HTTP API portissa 37777 web-katselukäyttöliittymällä ja 10 hakupäätepisteellä, Bun-hallinnoimana
4. **SQLite-tietokanta** - Tallentaa istunnot, havainnot, yhteenvedot
5. **mem-search-taito** - Luonnollisen kielen kyselyt asteittaisella paljastamisella
6. **Chroma-vektoritietokanta** - Hybridi semanttinen + avainsanahaku älykkääseen kontekstin hakuun
Katso [Arkkitehtuurin yleiskatsaus](https://docs.claude-mem.ai/architecture/overview) yksityiskohdista.
---
## mem-search-taito
Claude-Mem tarjoaa älykkään haun mem-search-taidon kautta, joka käynnistyy automaattisesti kun kysyt aiemmasta työstä:
**Miten se toimii:**
- Kysy vain luonnollisesti: *"Mitä teimme viime istunnossa?"* tai *"Korjasimmeko tämän bugin aiemmin?"*
- Claude käynnistää automaattisesti mem-search-taidon löytääkseen relevantin kontekstin
**Saatavilla olevat hakutoiminnot:**
1. **Hae havaintoja** - Koko tekstin haku havainnoissa
2. **Hae istuntoja** - Koko tekstin haku istuntojen yhteenvedoissa
3. **Hae prompteja** - Hae raakoista käyttäjäpyynnöistä
4. **Konseptin mukaan** - Hae konseptitageilla (discovery, problem-solution, pattern, jne.)
5. **Tiedoston mukaan** - Hae tiettyihin tiedostoihin viittaavia havaintoja
6. **Tyypin mukaan** - Hae tyypillä (decision, bugfix, feature, refactor, discovery, change)
7. **Viimeaikainen konteksti** - Hae projektin viimeaikainen istuntokonteksti
8. **Aikajana** - Hae yhtenäinen aikajana kontekstista tietyn ajankohdan ympärillä
9. **Aikajana kyselyn mukaan** - Hae havaintoja ja saa aikalinjakonteksti parhaan osuman ympärillä
10. **API-ohje** - Hae haku-API:n dokumentaatio
**Esimerkkejä luonnollisen kielen kyselyistä:**
```
"Mitkä bugit korjasimme viime istunnossa?"
"Miten toteutimme autentikoinnin?"
"Mitä muutoksia tehtiin worker-service.ts:ään?"
"Näytä viimeaikainen työ tässä projektissa"
"Mitä tapahtui kun lisäsimme katselukäyttöliittymän?"
```
Katso [Hakutyökalujen opas](https://docs.claude-mem.ai/usage/search-tools) yksityiskohtaisia esimerkkejä varten.
---
## Beta-ominaisuudet
Claude-Mem tarjoaa **beta-kanavan** kokeellisilla ominaisuuksilla kuten **Endless Mode** (biomimeettinen muistiarkkitehtuuri pidennetyille istunnoille). Vaihda vakaan ja beta-version välillä web-katselukäyttöliittymästä osoitteessa http://localhost:37777 → Settings.
Katso **[Beta-ominaisuuksien dokumentaatio](https://docs.claude-mem.ai/beta-features)** yksityiskohdista Endless Moden ja sen kokeilemisen osalta.
---
## Järjestelmävaatimukset
- **Node.js**: 18.0.0 tai uudempi
- **Claude Code**: Uusin versio plugin-tuella
- **Bun**: JavaScript-ajoympäristö ja prosessinhallinta (asennetaan automaattisesti jos puuttuu)
- **uv**: Python-paketinhallinta vektorihakuun (asennetaan automaattisesti jos puuttuu)
- **SQLite 3**: Pysyvälle tallennukselle (sisältyy)
---
## Asetukset
Asetuksia hallitaan tiedostossa `~/.claude-mem/settings.json` (luodaan automaattisesti oletusarvoilla ensimmäisellä suorituskerralla). Määritä AI-malli, worker-portti, datahakemisto, lokitaso ja kontekstin injektointiasetukset.
Katso **[Asetusopas](https://docs.claude-mem.ai/configuration)** kaikista saatavilla olevista asetuksista ja esimerkeistä.
---
## Kehitys
Katso **[Kehitysopas](https://docs.claude-mem.ai/development)** rakennusohjeista, testauksesta ja osallistumisen työnkulusta.
---
## Vianmääritys
Jos kohtaat ongelmia, kuvaile ongelma Claudelle ja troubleshoot-taito diagnosoi automaattisesti ja tarjoaa korjauksia.
Katso **[Vianmääritysopas](https://docs.claude-mem.ai/troubleshooting)** yleisistä ongelmista ja ratkaisuista.
---
## Bugiraportit
Luo kattavia bugiraportteja automaattisella generaattorilla:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Osallistuminen
Osallistuminen on tervetullutta! Ole hyvä:
1. Haarukoi repositorio
2. Luo ominaisuushaara
3. Tee muutoksesi testeineen
4. Päivitä dokumentaatio
5. Lähetä Pull Request
Katso [Kehitysopas](https://docs.claude-mem.ai/development) osallistumisen työnkulusta.
---
## Lisenssi
Tämä projekti on lisensoitu **GNU Affero General Public License v3.0** (AGPL-3.0) -lisenssillä.
Copyright (C) 2025 Alex Newman (@thedotmack). Kaikki oikeudet pidätetään.
Katso [LICENSE](LICENSE)-tiedosto täydellisistä yksityiskohdista.
**Mitä tämä tarkoittaa:**
- Voit käyttää, muokata ja jakaa tätä ohjelmistoa vapaasti
- Jos muokkaat ja otat käyttöön verkkopalvelimella, sinun on asetettava lähdekoodisi saataville
- Johdannaisten teosten on myös oltava AGPL-3.0-lisensoituja
- Tälle ohjelmistolle EI OLE TAKUUTA
**Huomautus Ragtimesta**: `ragtime/`-hakemisto on erikseen lisensoitu **PolyForm Noncommercial License 1.0.0** -lisenssillä. Katso [ragtime/LICENSE](ragtime/LICENSE) yksityiskohdista.
---
## Tuki
- **Dokumentaatio**: [docs/](docs/)
- **Ongelmat**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositorio**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Tekijä**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Rakennettu Claude Agent SDK:lla** | **Claude Coden voimalla** | **Tehty TypeScriptillä**

306
.agent/services/claude-mem/docs/i18n/README.fr.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 Ceci est une traduction automatisée. Les corrections de la communauté sont les bienvenues !
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Système de compression de mémoire persistante conçu pour <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#démarrage-rapide">Démarrage rapide</a> •
<a href="#comment-ça-fonctionne">Comment ça fonctionne</a> •
<a href="#compétence-mem-search">Outils de recherche</a> •
<a href="#documentation">Documentation</a> •
<a href="#configuration">Configuration</a> •
<a href="#dépannage">Dépannage</a> •
<a href="#licence">Licence</a>
</p>
<p align="center">
Claude-Mem préserve de manière transparente le contexte d'une session à l'autre en capturant automatiquement les observations d'utilisation des outils, en générant des résumés sémantiques et en les rendant disponibles pour les sessions futures. Cela permet à Claude de maintenir la continuité des connaissances sur les projets même après la fin des sessions ou la reconnexion.
</p>
---
## Démarrage rapide
Démarrez une nouvelle session Claude Code dans le terminal et saisissez les commandes suivantes :
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Redémarrez Claude Code. Le contexte des sessions précédentes apparaîtra automatiquement dans les nouvelles sessions.
**Fonctionnalités clés :**
- 🧠 **Mémoire persistante** - Le contexte survit d'une session à l'autre
- 📊 **Divulgation progressive** - Récupération de mémoire en couches avec visibilité du coût en tokens
- 🔍 **Recherche basée sur les compétences** - Interrogez l'historique de votre projet avec la compétence mem-search
- 🖥️ **Interface Web de visualisation** - Flux de mémoire en temps réel à http://localhost:37777
- 💻 **Compétence Claude Desktop** - Recherchez dans la mémoire depuis les conversations Claude Desktop
- 🔒 **Contrôle de la confidentialité** - Utilisez les balises `<private>` pour exclure le contenu sensible du stockage
- ⚙️ **Configuration du contexte** - Contrôle précis sur le contexte injecté
- 🤖 **Fonctionnement automatique** - Aucune intervention manuelle requise
- 🔗 **Citations** - Référencez les observations passées avec des ID (accès via http://localhost:37777/api/observation/{id} ou visualisez tout dans l'interface web à http://localhost:37777)
- 🧪 **Canal bêta** - Essayez des fonctionnalités expérimentales comme le mode Endless via le changement de version
---
## Documentation
📚 **[Voir la documentation complète](https://docs.claude-mem.ai/)** - Parcourir sur le site officiel
### Pour commencer
- **[Guide d'installation](https://docs.claude-mem.ai/installation)** - Démarrage rapide et installation avancée
- **[Guide d'utilisation](https://docs.claude-mem.ai/usage/getting-started)** - Comment Claude-Mem fonctionne automatiquement
- **[Outils de recherche](https://docs.claude-mem.ai/usage/search-tools)** - Interrogez l'historique de votre projet en langage naturel
- **[Fonctionnalités bêta](https://docs.claude-mem.ai/beta-features)** - Essayez des fonctionnalités expérimentales comme le mode Endless
### Bonnes pratiques
- **[Ingénierie du contexte](https://docs.claude-mem.ai/context-engineering)** - Principes d'optimisation du contexte pour les agents IA
- **[Divulgation progressive](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophie derrière la stratégie d'amorçage du contexte de Claude-Mem
### Architecture
- **[Vue d'ensemble](https://docs.claude-mem.ai/architecture/overview)** - Composants du système et flux de données
- **[Évolution de l'architecture](https://docs.claude-mem.ai/architecture-evolution)** - Le parcours de la v3 à la v5
- **[Architecture des hooks](https://docs.claude-mem.ai/hooks-architecture)** - Comment Claude-Mem utilise les hooks de cycle de vie
- **[Référence des hooks](https://docs.claude-mem.ai/architecture/hooks)** - Explication des 7 scripts de hooks
- **[Service Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP et gestion Bun
- **[Base de données](https://docs.claude-mem.ai/architecture/database)** - Schéma SQLite et recherche FTS5
- **[Architecture de recherche](https://docs.claude-mem.ai/architecture/search-architecture)** - Recherche hybride avec la base de données vectorielle Chroma
### Configuration et développement
- **[Configuration](https://docs.claude-mem.ai/configuration)** - Variables d'environnement et paramètres
- **[Développement](https://docs.claude-mem.ai/development)** - Compilation, tests, contribution
- **[Dépannage](https://docs.claude-mem.ai/troubleshooting)** - Problèmes courants et solutions
---
## Comment ça fonctionne
**Composants principaux :**
1. **5 hooks de cycle de vie** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripts de hooks)
2. **Installation intelligente** - Vérificateur de dépendances en cache (script pré-hook, pas un hook de cycle de vie)
3. **Service Worker** - API HTTP sur le port 37777 avec interface web de visualisation et 10 points de terminaison de recherche, géré par Bun
4. **Base de données SQLite** - Stocke les sessions, observations, résumés
5. **Compétence mem-search** - Requêtes en langage naturel avec divulgation progressive
6. **Base de données vectorielle Chroma** - Recherche hybride sémantique + mots-clés pour une récupération de contexte intelligente
Voir [Vue d'ensemble de l'architecture](https://docs.claude-mem.ai/architecture/overview) pour plus de détails.
---
## Compétence mem-search
Claude-Mem fournit une recherche intelligente via la compétence mem-search qui s'invoque automatiquement lorsque vous posez des questions sur le travail passé :
**Comment ça fonctionne :**
- Posez simplement des questions naturellement : *"Qu'avons-nous fait lors de la dernière session ?"* ou *"Avons-nous déjà corrigé ce bug ?"*
- Claude invoque automatiquement la compétence mem-search pour trouver le contexte pertinent
**Opérations de recherche disponibles :**
1. **Rechercher des observations** - Recherche plein texte dans les observations
2. **Rechercher des sessions** - Recherche plein texte dans les résumés de sessions
3. **Rechercher des invites** - Rechercher dans les demandes brutes des utilisateurs
4. **Par concept** - Trouver par étiquettes de concept (discovery, problem-solution, pattern, etc.)
5. **Par fichier** - Trouver les observations faisant référence à des fichiers spécifiques
6. **Par type** - Trouver par type (decision, bugfix, feature, refactor, discovery, change)
7. **Contexte récent** - Obtenir le contexte récent d'une session pour un projet
8. **Timeline** - Obtenir une chronologie unifiée du contexte autour d'un point spécifique dans le temps
9. **Timeline par requête** - Rechercher des observations et obtenir le contexte de la chronologie autour de la meilleure correspondance
10. **Aide API** - Obtenir la documentation de l'API de recherche
**Exemples de requêtes en langage naturel :**
```
"Quels bugs avons-nous corrigés lors de la dernière session ?"
"Comment avons-nous implémenté l'authentification ?"
"Quels changements ont été apportés à worker-service.ts ?"
"Montrez-moi le travail récent sur ce projet"
"Que se passait-il lorsque nous avons ajouté l'interface de visualisation ?"
```
Voir le [Guide des outils de recherche](https://docs.claude-mem.ai/usage/search-tools) pour des exemples détaillés.
---
## Fonctionnalités bêta
Claude-Mem propose un **canal bêta** avec des fonctionnalités expérimentales comme le **mode Endless** (architecture de mémoire biomimétique pour les sessions étendues). Basculez entre les versions stables et bêta depuis l'interface web de visualisation à http://localhost:37777 → Paramètres.
Voir la **[Documentation des fonctionnalités bêta](https://docs.claude-mem.ai/beta-features)** pour plus de détails sur le mode Endless et comment l'essayer.
---
## Configuration système requise
- **Node.js** : 18.0.0 ou supérieur
- **Claude Code** : Dernière version avec support des plugins
- **Bun** : Runtime JavaScript et gestionnaire de processus (installé automatiquement si manquant)
- **uv** : Gestionnaire de packages Python pour la recherche vectorielle (installé automatiquement si manquant)
- **SQLite 3** : Pour le stockage persistant (inclus)
---
## Configuration
Les paramètres sont gérés dans `~/.claude-mem/settings.json` (créé automatiquement avec les valeurs par défaut au premier lancement). Configurez le modèle IA, le port du worker, le répertoire de données, le niveau de journalisation et les paramètres d'injection de contexte.
Voir le **[Guide de configuration](https://docs.claude-mem.ai/configuration)** pour tous les paramètres disponibles et des exemples.
---
## Développement
Voir le **[Guide de développement](https://docs.claude-mem.ai/development)** pour les instructions de compilation, les tests et le flux de contribution.
---
## Dépannage
Si vous rencontrez des problèmes, décrivez le problème à Claude et la compétence troubleshoot diagnostiquera automatiquement et fournira des solutions.
Voir le **[Guide de dépannage](https://docs.claude-mem.ai/troubleshooting)** pour les problèmes courants et les solutions.
---
## Rapports de bugs
Créez des rapports de bugs complets avec le générateur automatisé :
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contribuer
Les contributions sont les bienvenues ! Veuillez :
1. Forker le dépôt
2. Créer une branche de fonctionnalité
3. Effectuer vos modifications avec des tests
4. Mettre à jour la documentation
5. Soumettre une Pull Request
Voir le [Guide de développement](https://docs.claude-mem.ai/development) pour le flux de contribution.
---
## Licence
Ce projet est sous licence **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Tous droits réservés.
Voir le fichier [LICENSE](LICENSE) pour tous les détails.
**Ce que cela signifie :**
- Vous pouvez utiliser, modifier et distribuer ce logiciel librement
- Si vous modifiez et déployez sur un serveur réseau, vous devez rendre votre code source disponible
- Les œuvres dérivées doivent également être sous licence AGPL-3.0
- Il n'y a AUCUNE GARANTIE pour ce logiciel
**Note sur Ragtime** : Le répertoire `ragtime/` est sous licence séparée sous la **PolyForm Noncommercial License 1.0.0**. Voir [ragtime/LICENSE](ragtime/LICENSE) pour plus de détails.
---
## Support
- **Documentation** : [docs/](docs/)
- **Issues** : [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Dépôt** : [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Auteur** : Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Construit avec Claude Agent SDK** | **Propulsé par Claude Code** | **Fait avec TypeScript**
---

303
.agent/services/claude-mem/docs/i18n/README.he.md Normal file
View File

@@ -0,0 +1,303 @@
🌐 זהו תרגום אוטומטי. תיקונים מהקהילה יתקבלו בברכה!
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">מערכת דחיסת זיכרון מתמשך שנבנתה עבור <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#quick-start">התחלה מהירה</a> •
<a href="#how-it-works">איך זה עובד</a> •
<a href="#mcp-search-tools">כלי חיפוש</a> •
<a href="#documentation">תיעוד</a> •
<a href="#configuration">הגדרות</a> •
<a href="#troubleshooting">פתרון בעיות</a> •
<a href="#license">רישיון</a>
</p>
<p align="center">
Claude-Mem משמר הקשר בצורה חלקה בין הפעלות על ידי לכידה אוטומטית של תצפיות על שימוש בכלים, יצירת סיכומים סמנטיים, והנגשתם להפעלות עתידיות. זה מאפשר ל-Claude לשמור על המשכיות של ידע על פרויקטים גם לאחר שהפעלות מסתיימות או מתחברות מחדש.
</p>
---
## התחלה מהירה
התחל הפעלה חדשה של Claude Code בטרמינל והזן את הפקודות הבאות:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
הפעל מחדש את Claude Code. הקשר מהפעלות קודמות יופיע אוטומטית בהפעלות חדשות.
**תכונות עיקריות:**
- 🧠 **זיכרון מתמשך** - הקשר שורד בין הפעלות
- 📊 **גילוי מדורג** - אחזור זיכרון רב-שכבתי עם נראות עלות טוקנים
- 🔍 **חיפוש מבוסס-מיומנויות** - שאל את היסטוריית הפרויקט שלך עם מיומנות mem-search
- 🖥️ **ממשק צופה אינטרנט** - זרימת זיכרון בזמן אמת ב-http://localhost:37777
- 💻 **מיומנות Claude Desktop** - חפש זיכרון משיחות Claude Desktop
- 🔒 **בקרת פרטיות** - השתמש בתגיות `<private>` כדי להוציא תוכן רגיש מהאחסון
- ⚙️ **הגדרות הקשר** - בקרה מדויקת על איזה הקשר מוזרק
- 🤖 **פעולה אוטומטית** - אין צורך בהתערבות ידנית
- 🔗 **ציטוטים** - הפנה לתצפיות קודמות עם מזהים (גישה דרך http://localhost:37777/api/observation/{id} או צפה בכולם בצופה האינטרנט ב-http://localhost:37777)
- 🧪 **ערוץ בטא** - נסה תכונות ניסיוניות כמו Endless Mode דרך החלפת גרסאות
---
## תיעוד
📚 **[צפה בתיעוד המלא](https://docs.claude-mem.ai/)** - דפדף באתר הרשמי
### תחילת העבודה
- **[מדריך התקנה](https://docs.claude-mem.ai/installation)** - התחלה מהירה והתקנה מתקדמת
- **[מדריך שימוש](https://docs.claude-mem.ai/usage/getting-started)** - איך Claude-Mem עובד אוטומטית
- **[כלי חיפוש](https://docs.claude-mem.ai/usage/search-tools)** - שאל את היסטוריית הפרויקט שלך בשפה טבעית
- **[תכונות בטא](https://docs.claude-mem.ai/beta-features)** - נסה תכונות ניסיוניות כמו Endless Mode
### שיטות מומלצות
- **[הנדסת הקשר](https://docs.claude-mem.ai/context-engineering)** - עקרונות אופטימיזציה של הקשר לסוכן AI
- **[גילוי מדורג](https://docs.claude-mem.ai/progressive-disclosure)** - הפילוסופיה מאחורי אסטרטגיית הכנת ההקשר של Claude-Mem
### ארכיטקטורה
- **[סקירה כללית](https://docs.claude-mem.ai/architecture/overview)** - רכיבי המערכת וזרימת הנתונים
- **[התפתחות הארכיטקטורה](https://docs.claude-mem.ai/architecture-evolution)** - המסע מגרסה 3 לגרסה 5
- **[ארכיטקטורת Hooks](https://docs.claude-mem.ai/hooks-architecture)** - איך Claude-Mem משתמש ב-lifecycle hooks
- **[מדריך Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 סקריפטי hook מוסברים
- **[שירות Worker](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API וניהול Bun
- **[מסד נתונים](https://docs.claude-mem.ai/architecture/database)** - סכמת SQLite וחיפוש FTS5
- **[ארכיטקטורת חיפוש](https://docs.claude-mem.ai/architecture/search-architecture)** - חיפוש היברידי עם מסד נתוני וקטורים Chroma
### הגדרות ופיתוח
- **[הגדרות](https://docs.claude-mem.ai/configuration)** - משתני סביבה והגדרות
- **[פיתוח](https://docs.claude-mem.ai/development)** - בנייה, בדיקה, תרומה
- **[פתרון בעיות](https://docs.claude-mem.ai/troubleshooting)** - בעיות נפוצות ופתרונות
---
## איך זה עובד
**רכיבי ליבה:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 סקריפטי hook)
2. **התקנה חכמה** - בודק תלויות עם מטמון (סקריפט pre-hook, לא lifecycle hook)
3. **שירות Worker** - HTTP API על פורט 37777 עם ממשק צופה אינטרנט ו-10 נקודות קצה לחיפוש, מנוהל על ידי Bun
4. **מסד נתוני SQLite** - מאחסן הפעלות, תצפיות, סיכומים
5. **מיומנות mem-search** - שאילתות בשפה טבעית עם גילוי מדורג
6. **מסד נתוני וקטורים Chroma** - חיפוש היברידי סמנטי + מילות מפתח לאחזור הקשר חכם
ראה [סקירה כללית של הארכיטקטורה](https://docs.claude-mem.ai/architecture/overview) לפרטים.
---
## מיומנות mem-search
Claude-Mem מספק חיפוש חכם דרך מיומנות mem-search שמופעלת אוטומטית כשאתה שואל על עבודה קודמת:
**איך זה עובד:**
- פשוט שאל באופן טבעי: *"מה עשינו בהפעלה האחרונה?"* או *"תיקנו את הבאג הזה קודם?"*
- Claude מפעיל אוטומטית את מיומנות mem-search כדי למצוא הקשר רלוונטי
**פעולות חיפוש זמינות:**
1. **חיפוש תצפיות** - חיפוש טקסט מלא על פני תצפיות
2. **חיפוש הפעלות** - חיפוש טקסט מלא על פני סיכומי הפעלות
3. **חיפוש Prompts** - חיפוש בקשות משתמש גולמיות
4. **לפי מושג** - חיפוש לפי תגיות מושג (discovery, problem-solution, pattern, וכו')
5. **לפי קובץ** - חיפוש תצפיות המתייחסות לקבצים ספציפיים
6. **לפי סוג** - חיפוש לפי סוג (decision, bugfix, feature, refactor, discovery, change)
7. **הקשר אחרון** - קבל הקשר הפעלות אחרון לפרויקט
8. **ציר זמן** - קבל ציר זמן מאוחד של הקשר סביב נקודת זמן ספציפית
9. **ציר זמן לפי שאילתה** - חפש תצפיות וקבל הקשר ציר זמן סביב ההתאמה הטובה ביותר
10. **עזרה ל-API** - קבל תיעוד API חיפוש
**דוגמאות לשאילתות בשפה טבעית:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
ראה [מדריך כלי חיפוש](https://docs.claude-mem.ai/usage/search-tools) לדוגמאות מפורטות.
---
## תכונות בטא
Claude-Mem מציע **ערוץ בטא** עם תכונות ניסיוניות כמו **Endless Mode** (ארכיטקטורת זיכרון ביומימטית להפעלות מורחבות). החלף בין גרסאות יציבות ובטא מממשק הצופה האינטרנט ב-http://localhost:37777 → Settings.
ראה **[תיעוד תכונות בטא](https://docs.claude-mem.ai/beta-features)** לפרטים על Endless Mode ואיך לנסות אותו.
---
## דרישות מערכת
- **Node.js**: 18.0.0 ומעלה
- **Claude Code**: גרסה אחרונה עם תמיכה בתוספים
- **Bun**: סביבת ריצה ומנהל תהליכים של JavaScript (מותקן אוטומטית אם חסר)
- **uv**: מנהל חבילות Python לחיפוש וקטורי (מותקן אוטומטית אם חסר)
- **SQLite 3**: לאחסון מתמשך (מצורף)
---
## הגדרות
ההגדרות מנוהלות ב-`~/.claude-mem/settings.json` (נוצר אוטומטית עם ברירות מחדל בהפעלה הראשונה). הגדר מודל AI, פורט worker, ספריית נתונים, רמת לוג, והגדרות הזרקת הקשר.
ראה **[מדריך הגדרות](https://docs.claude-mem.ai/configuration)** לכל ההגדרות הזמינות ודוגמאות.
---
## פיתוח
ראה **[מדריך פיתוח](https://docs.claude-mem.ai/development)** להוראות בנייה, בדיקה, ותהליך תרומה.
---
## פתרון בעיות
אם אתה נתקל בבעיות, תאר את הבעיה ל-Claude ומיומנות troubleshoot תאבחן אוטומטית ותספק תיקונים.
ראה **[מדריך פתרון בעיות](https://docs.claude-mem.ai/troubleshooting)** לבעיות נפוצות ופתרונות.
---
## דיווחי באגים
צור דיווחי באגים מקיפים עם המחולל האוטומטי:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## תרומה
תרומות מתקבלות בברכה! אנא:
1. עשה Fork למאגר
2. צור ענף תכונה
3. בצע את השינויים שלך עם בדיקות
4. עדכן תיעוד
5. שלח Pull Request
ראה [מדריך פיתוח](https://docs.claude-mem.ai/development) לתהליך תרומה.
---
## רישיון
פרויקט זה מורשה תחת **GNU Affero General Public License v3.0** (AGPL-3.0).
זכויות יוצרים (C) 2025 Alex Newman (@thedotmack). כל הזכויות שמורות.
ראה את קובץ [LICENSE](LICENSE) לפרטים מלאים.
**משמעות הדבר:**
- אתה יכול לשימוש, שינוי והפצה של תוכנה זו בחופשיות
- אם אתה משנה ופורס על שרת רשת, עליך להנגיש את קוד המקור שלך
- עבודות נגזרות חייבות להיות מורשות גם כן תחת AGPL-3.0
- אין אחריות לתוכנה זו
**הערה על Ragtime**: ספריית `ragtime/` מורשית בנפרד תחת **PolyForm Noncommercial License 1.0.0**. ראה [ragtime/LICENSE](ragtime/LICENSE) לפרטים.
---
## תמיכה
- **תיעוד**: [docs/](docs/)
- **בעיות**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **מאגר**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **מחבר**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**נבנה עם Claude Agent SDK** | **מופעל על ידי Claude Code** | **נוצר עם TypeScript**

306
.agent/services/claude-mem/docs/i18n/README.hi.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 यह एक स्वचालित अनुवाद है। समुदाय से सुधार का स्वागत है!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center"><a href="https://claude.com/claude-code" target="_blank">Claude Code</a> के लिए बनाई गई स्थायी मेमोरी संपीड़न प्रणाली।</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#quick-start">त्वरित शुरुआत</a> •
<a href="#how-it-works">यह कैसे काम करता है</a> •
<a href="#mcp-search-tools">खोज उपकरण</a> •
<a href="#documentation">दस्तावेज़ीकरण</a> •
<a href="#configuration">कॉन्फ़िगरेशन</a> •
<a href="#troubleshooting">समस्या निवारण</a> •
<a href="#license">लाइसेंस</a>
</p>
<p align="center">
Claude-Mem स्वचालित रूप से टूल उपयोग अवलोकनों को कैप्चर करके, सिमेंटिक सारांश उत्पन्न करके, और उन्हें भविष्य के सत्रों के लिए उपलब्ध कराकर सत्रों में संदर्भ को निर्बाध रूप से संरक्षित करता है। यह Claude को परियोजनाओं के बारे में ज्ञान की निरंतरता बनाए रखने में सक्षम बनाता है, भले ही सत्र समाप्त हो जाएं या पुनः कनेक्ट हो जाएं।
</p>
---
## त्वरित शुरुआत
टर्मिनल में एक नया Claude Code सत्र शुरू करें और निम्नलिखित कमांड दर्ज करें:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Claude Code को पुनः आरंभ करें। पिछले सत्रों का संदर्भ स्वचालित रूप से नए सत्रों में दिखाई देगा।
**मुख्य विशेषताएं:**
- 🧠 **स्थायी मेमोरी** - संदर्भ सत्रों में बना रहता है
- 📊 **प्रगतिशील प्रकटीकरण** - टोकन लागत दृश्यता के साथ स्तरित मेमोरी पुनर्प्राप्ति
- 🔍 **स्किल-आधारित खोज** - mem-search स्किल के साथ अपने प्रोजेक्ट इतिहास को क्वेरी करें
- 🖥️ **वेब व्यूअर UI** - http://localhost:37777 पर रीयल-टाइम मेमोरी स्ट्रीम
- 💻 **Claude Desktop स्किल** - Claude Desktop वार्तालापों से मेमोरी खोजें
- 🔒 **गोपनीयता नियंत्रण** - संवेदनशील सामग्री को स्टोरेज से बाहर रखने के लिए `<private>` टैग का उपयोग करें
- ⚙️ **संदर्भ कॉन्फ़िगरेशन** - किस संदर्भ को इंजेक्ट किया जाता है, इस पर सूक्ष्म नियंत्रण
- 🤖 **स्वचालित संचालन** - मैन्युअल हस्तक्षेप की आवश्यकता नहीं
- 🔗 **उद्धरण** - IDs के साथ पिछले अवलोकनों का संदर्भ दें (http://localhost:37777/api/observation/{id} के माध्यम से एक्सेस करें या http://localhost:37777 पर वेब व्यूअर में सभी देखें)
- 🧪 **बीटा चैनल** - संस्करण स्विचिंग के माध्यम से Endless Mode जैसी प्रायोगिक सुविधाओं को आज़माएं
---
## दस्तावेज़ीकरण
📚 **[पूर्ण दस्तावेज़ीकरण देखें](https://docs.claude-mem.ai/)** - आधिकारिक वेबसाइट पर ब्राउज़ करें
### शुरुआत करना
- **[इंस्टॉलेशन गाइड](https://docs.claude-mem.ai/installation)** - त्वरित शुरुआत और उन्नत इंस्टॉलेशन
- **[उपयोग गाइड](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem स्वचालित रूप से कैसे काम करता है
- **[खोज उपकरण](https://docs.claude-mem.ai/usage/search-tools)** - प्राकृतिक भाषा के साथ अपने प्रोजेक्ट इतिहास को क्वेरी करें
- **[बीटा सुविधाएं](https://docs.claude-mem.ai/beta-features)** - Endless Mode जैसी प्रायोगिक सुविधाओं को आज़माएं
### सर्वोत्तम अभ्यास
- **[संदर्भ इंजीनियरिंग](https://docs.claude-mem.ai/context-engineering)** - AI एजेंट संदर्भ अनुकूलन सिद्धांत
- **[प्रगतिशील प्रकटीकरण](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem की संदर्भ प्राइमिंग रणनीति के पीछे का दर्शन
### आर्किटेक्चर
- **[अवलोकन](https://docs.claude-mem.ai/architecture/overview)** - सिस्टम घटक और डेटा प्रवाह
- **[आर्किटेक्चर विकास](https://docs.claude-mem.ai/architecture-evolution)** - v3 से v5 तक की यात्रा
- **[Hooks आर्किटेक्चर](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem जीवनचक्र hooks का उपयोग कैसे करता है
- **[Hooks संदर्भ](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook स्क्रिप्ट समझाई गई
- **[Worker सेवा](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API और Bun प्रबंधन
- **[डेटाबेस](https://docs.claude-mem.ai/architecture/database)** - SQLite स्कीमा और FTS5 खोज
- **[खोज आर्किटेक्चर](https://docs.claude-mem.ai/architecture/search-architecture)** - Chroma वेक्टर डेटाबेस के साथ हाइब्रिड खोज
### कॉन्फ़िगरेशन और विकास
- **[कॉन्फ़िगरेशन](https://docs.claude-mem.ai/configuration)** - पर्यावरण चर और सेटिंग्स
- **[विकास](https://docs.claude-mem.ai/development)** - बिल्डिंग, परीक्षण, योगदान
- **[समस्या निवारण](https://docs.claude-mem.ai/troubleshooting)** - सामान्य समस्याएं और समाधान
---
## यह कैसे काम करता है
**मुख्य घटक:**
1. **5 जीवनचक्र Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook स्क्रिप्ट)
2. **स्मार्ट इंस्टॉल** - कैश्ड डिपेंडेंसी चेकर (pre-hook स्क्रिप्ट, जीवनचक्र hook नहीं)
3. **Worker सेवा** - वेब व्यूअर UI और 10 खोज endpoints के साथ पोर्ट 37777 पर HTTP API, Bun द्वारा प्रबंधित
4. **SQLite डेटाबेस** - सत्र, अवलोकन, सारांश संग्रहीत करता है
5. **mem-search स्किल** - प्रगतिशील प्रकटीकरण के साथ प्राकृतिक भाषा क्वेरी
6. **Chroma वेक्टर डेटाबेस** - बुद्धिमान संदर्भ पुनर्प्राप्ति के लिए हाइब्रिड सिमेंटिक + कीवर्ड खोज
विवरण के लिए [आर्किटेक्चर अवलोकन](https://docs.claude-mem.ai/architecture/overview) देखें।
---
## mem-search स्किल
Claude-Mem mem-search स्किल के माध्यम से बुद्धिमान खोज प्रदान करता है जो स्वचालित रूप से सक्रिय हो जाती है जब आप पिछले काम के बारे में पूछते हैं:
**यह कैसे काम करता है:**
- बस स्वाभाविक रूप से पूछें: *"हमने पिछले सत्र में क्या किया?"* या *"क्या हमने पहले इस बग को ठीक किया था?"*
- Claude स्वचालित रूप से प्रासंगिक संदर्भ खोजने के लिए mem-search स्किल को सक्रिय करता है
**उपलब्ध खोज संचालन:**
1. **अवलोकन खोजें** - अवलोकनों में पूर्ण-पाठ खोज
2. **सत्र खोजें** - सत्र सारांशों में पूर्ण-पाठ खोज
3. **प्रॉम्प्ट खोजें** - कच्चे उपयोगकर्ता अनुरोध खोजें
4. **अवधारणा द्वारा** - अवधारणा टैग द्वारा खोजें (discovery, problem-solution, pattern, आदि)
5. **फ़ाइल द्वारा** - विशिष्ट फ़ाइलों का संदर्भ देने वाले अवलोकन खोजें
6. **प्रकार द्वारा** - प्रकार द्वारा खोजें (decision, bugfix, feature, refactor, discovery, change)
7. **हालिया संदर्भ** - एक प्रोजेक्ट के लिए हालिया सत्र संदर्भ प्राप्त करें
8. **टाइमलाइन** - समय में एक विशिष्ट बिंदु के आसपास संदर्भ की एकीकृत टाइमलाइन प्राप्त करें
9. **क्वेरी द्वारा टाइमलाइन** - अवलोकनों को खोजें और सर्वश्रेष्ठ मिलान के आसपास टाइमलाइन संदर्भ प्राप्त करें
10. **API सहायता** - खोज API दस्तावेज़ीकरण प्राप्त करें
**प्राकृतिक भाषा क्वेरी के उदाहरण:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
विस्तृत उदाहरणों के लिए [खोज उपकरण गाइड](https://docs.claude-mem.ai/usage/search-tools) देखें।
---
## बीटा सुविधाएं
Claude-Mem **बीटा चैनल** के साथ **Endless Mode** (विस्तारित सत्रों के लिए बायोमिमेटिक मेमोरी आर्किटेक्चर) जैसी प्रायोगिक सुविधाएं प्रदान करता है। http://localhost:37777 → Settings पर वेब व्यूअर UI से स्थिर और बीटा संस्करणों के बीच स्विच करें।
Endless Mode के विवरण और इसे आज़माने के तरीके के लिए **[बीटा सुविधाएं दस्तावेज़ीकरण](https://docs.claude-mem.ai/beta-features)** देखें।
---
## सिस्टम आवश्यकताएं
- **Node.js**: 18.0.0 या उच्चतर
- **Claude Code**: प्लगइन समर्थन के साथ नवीनतम संस्करण
- **Bun**: JavaScript रनटाइम और प्रोसेस मैनेजर (यदि गायब हो तो ऑटो-इंस्टॉल)
- **uv**: वेक्टर खोज के लिए Python पैकेज मैनेजर (यदि गायब हो तो ऑटो-इंस्टॉल)
- **SQLite 3**: स्थायी स्टोरेज के लिए (बंडल किया गया)
---
## कॉन्फ़िगरेशन
सेटिंग्स `~/.claude-mem/settings.json` में प्रबंधित की जाती हैं (पहली बार चलने पर डिफ़ॉल्ट के साथ ऑटो-निर्मित)। AI मॉडल, worker पोर्ट, डेटा डायरेक्टरी, लॉग स्तर, और संदर्भ इंजेक्शन सेटिंग्स कॉन्फ़िगर करें।
सभी उपलब्ध सेटिंग्स और उदाहरणों के लिए **[कॉन्फ़िगरेशन गाइड](https://docs.claude-mem.ai/configuration)** देखें।
---
## विकास
बिल्ड निर्देश, परीक्षण, और योगदान वर्कफ़्लो के लिए **[विकास गाइड](https://docs.claude-mem.ai/development)** देखें।
---
## समस्या निवारण
यदि समस्याओं का सामना कर रहे हैं, तो Claude को समस्या का वर्णन करें और troubleshoot स्किल स्वचालित रूप से निदान करेगी और सुधार प्रदान करेगी।
सामान्य समस्याओं और समाधानों के लिए **[समस्या निवारण गाइड](https://docs.claude-mem.ai/troubleshooting)** देखें।
---
## बग रिपोर्ट
स्वचालित जेनरेटर के साथ व्यापक बग रिपोर्ट बनाएं:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## योगदान
योगदान का स्वागत है! कृपया:
1. रिपॉजिटरी को Fork करें
2. एक feature ब्रांच बनाएं
3. परीक्षणों के साथ अपने परिवर्तन करें
4. दस्तावेज़ीकरण अपडेट करें
5. एक Pull Request सबमिट करें
योगदान वर्कफ़्लो के लिए [विकास गाइड](https://docs.claude-mem.ai/development) देखें।
---
## लाइसेंस
यह प्रोजेक्ट **GNU Affero General Public License v3.0** (AGPL-3.0) के तहत लाइसेंस प्राप्त है।
Copyright (C) 2025 Alex Newman (@thedotmack)। सर्वाधिकार सुरक्षित।
पूर्ण विवरण के लिए [LICENSE](LICENSE) फ़ाइल देखें।
**इसका क्या अर्थ है:**
- आप इस सॉफ़्टवेयर को स्वतंत्र रूप से उपयोग, संशोधित और वितरित कर सकते हैं
- यदि आप नेटवर्क सर्वर पर संशोधित और तैनात करते हैं, तो आपको अपना स्रोत कोड उपलब्ध कराना होगा
- व्युत्पन्न कार्यों को भी AGPL-3.0 के तहत लाइसेंस प्राप्त होना चाहिए
- इस सॉफ़्टवेयर के लिए कोई वारंटी नहीं है
**Ragtime पर नोट**: `ragtime/` डायरेक्टरी को **PolyForm Noncommercial License 1.0.0** के तहत अलग से लाइसेंस प्राप्त है। विवरण के लिए [ragtime/LICENSE](ragtime/LICENSE) देखें।
---
## समर्थन
- **दस्तावेज़ीकरण**: [docs/](docs/)
- **समस्याएं**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **रिपॉजिटरी**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **लेखक**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDK के साथ निर्मित** | **Claude Code द्वारा संचालित** | **TypeScript के साथ बनाया गया**
---

304
.agent/services/claude-mem/docs/i18n/README.hu.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Ez egy automatikus fordítás. Közösségi javítások szívesen fogadottak!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Tartós memória tömörítési rendszer a <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> számára.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#gyors-kezdés">Gyors kezdés</a> •
<a href="#hogyan-működik">Hogyan működik</a> •
<a href="#keresési-eszközök">Keresési eszközök</a> •
<a href="#dokumentáció">Dokumentáció</a> •
<a href="#konfiguráció">Konfiguráció</a> •
<a href="#hibaelhárítás">Hibaelhárítás</a> •
<a href="#licenc">Licenc</a>
</p>
<p align="center">
A Claude-Mem zökkenőmentesen megőrzi a kontextust munkamenetek között azáltal, hogy automatikusan rögzíti az eszközhasználati megfigyeléseket, szemantikus összefoglalókat generál, és elérhetővé teszi azokat a jövőbeli munkamenetekben. Ez lehetővé teszi Claude számára, hogy fenntartsa a projektekkel kapcsolatos tudás folytonosságát még a munkamenetek befejezése vagy újracsatlakozása után is.
</p>
---
## Gyors kezdés
Indítson el egy új Claude Code munkamenetet a terminálban, és írja be a következő parancsokat:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Indítsa újra a Claude Code-ot. A korábbi munkamenetek kontextusa automatikusan megjelenik az új munkamenetekben.
**Főbb jellemzők:**
- 🧠 **Tartós memória** - A kontextus túléli a munkameneteket
- 📊 **Progresszív felfedés** - Többrétegű memória-visszakeresés token költség láthatósággal
- 🔍 **Skill-alapú keresés** - Lekérdezheti projekt előzményeit a mem-search skill segítségével
- 🖥️ **Webes megjelenítő felület** - Valós idejű memória stream a http://localhost:37777 címen
- 💻 **Claude Desktop Skill** - Memória keresése Claude Desktop beszélgetésekből
- 🔒 **Adatvédelmi kontroll** - Használja a `<private>` címkéket az érzékeny tartalom kizárásához
- ⚙️ **Kontextus konfiguráció** - Finomhangolt kontroll afelett, hogy milyen kontextus kerül beillesztésre
- 🤖 **Automatikus működés** - Nincs szükség manuális beavatkozásra
- 🔗 **Hivatkozások** - Hivatkozás múltbeli megfigyelésekre ID-kkal (hozzáférés: http://localhost:37777/api/observation/{id} vagy mindegyik megtekintése a webes felületen a http://localhost:37777 címen)
- 🧪 **Béta csatorna** - Kísérleti funkciók, mint az Endless Mode kipróbálása verziócserével
---
## Dokumentáció
📚 **[Teljes dokumentáció megtekintése](https://docs.claude-mem.ai/)** - Böngészés a hivatalos weboldalon
### Első lépések
- **[Telepítési útmutató](https://docs.claude-mem.ai/installation)** - Gyors indítás és haladó telepítés
- **[Használati útmutató](https://docs.claude-mem.ai/usage/getting-started)** - Hogyan működik automatikusan a Claude-Mem
- **[Keresési eszközök](https://docs.claude-mem.ai/usage/search-tools)** - Projekt előzmények lekérdezése természetes nyelvvel
- **[Béta funkciók](https://docs.claude-mem.ai/beta-features)** - Kísérleti funkciók, mint az Endless Mode kipróbálása
### Bevált gyakorlatok
- **[Kontextus tervezés](https://docs.claude-mem.ai/context-engineering)** - AI ügynök kontextus optimalizálási elvek
- **[Progresszív felfedés](https://docs.claude-mem.ai/progressive-disclosure)** - A Claude-Mem kontextus előkészítési stratégiájának filozófiája
### Architektúra
- **[Áttekintés](https://docs.claude-mem.ai/architecture/overview)** - Rendszerkomponensek és adatfolyam
- **[Architektúra fejlődés](https://docs.claude-mem.ai/architecture-evolution)** - Az út a v3-tól a v5-ig
- **[Hooks architektúra](https://docs.claude-mem.ai/hooks-architecture)** - Hogyan használja a Claude-Mem az életciklus hookokat
- **[Hooks referencia](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook szkript magyarázata
- **[Worker szolgáltatás](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API és Bun kezelés
- **[Adatbázis](https://docs.claude-mem.ai/architecture/database)** - SQLite séma és FTS5 keresés
- **[Keresési architektúra](https://docs.claude-mem.ai/architecture/search-architecture)** - Hibrid keresés Chroma vektor adatbázissal
### Konfiguráció és fejlesztés
- **[Konfiguráció](https://docs.claude-mem.ai/configuration)** - Környezeti változók és beállítások
- **[Fejlesztés](https://docs.claude-mem.ai/development)** - Építés, tesztelés, hozzájárulás
- **[Hibaelhárítás](https://docs.claude-mem.ai/troubleshooting)** - Gyakori problémák és megoldások
---
## Hogyan működik
**Fő komponensek:**
1. **5 életciklus hook** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook szkript)
2. **Intelligens telepítés** - Gyorsítótárazott függőség ellenőrző (pre-hook szkript, nem életciklus hook)
3. **Worker szolgáltatás** - HTTP API a 37777-es porton webes megjelenítő felülettel és 10 keresési végponttal, Bun által kezelve
4. **SQLite adatbázis** - Munkamenetek, megfigyelések, összefoglalók tárolása
5. **mem-search Skill** - Természetes nyelvi lekérdezések progresszív felfedéssel
6. **Chroma vektor adatbázis** - Hibrid szemantikus + kulcsszó keresés intelligens kontextus visszakereséshez
További részletekért lásd az [Architektúra áttekintést](https://docs.claude-mem.ai/architecture/overview).
---
## mem-search Skill
A Claude-Mem intelligens keresést biztosít a mem-search skillen keresztül, amely automatikusan aktiválódik, amikor múltbeli munkáról kérdez:
**Hogyan működik:**
- Csak kérdezzen természetesen: *"Mit csináltunk az előző munkamenetben?"* vagy *"Javítottuk már ezt a hibát korábban?"*
- Claude automatikusan meghívja a mem-search skillet a releváns kontextus megtalálásához
**Elérhető keresési műveletek:**
1. **Megfigyelések keresése** - Teljes szöveges keresés a megfigyelésekben
2. **Munkamenetek keresése** - Teljes szöveges keresés munkamenet összefoglalókban
3. **Promptok keresése** - Nyers felhasználói kérések keresése
4. **Koncepció szerint** - Keresés koncepció címkék alapján (discovery, problem-solution, pattern, stb.)
5. **Fájl szerint** - Adott fájlokra hivatkozó megfigyelések keresése
6. **Típus szerint** - Keresés típus alapján (decision, bugfix, feature, refactor, discovery, change)
7. **Legutóbbi kontextus** - Legutóbbi munkamenet kontextus lekérése egy projekthez
8. **Idővonal** - Egységes idővonal kontextus lekérése egy adott időpont körül
9. **Idővonal lekérdezéssel** - Megfigyelések keresése és idővonal kontextus lekérése a legjobb találat körül
10. **API segítség** - Keresési API dokumentáció lekérése
**Példa természetes nyelvi lekérdezésekre:**
```
"Milyen hibákat javítottunk az előző munkamenetben?"
"Hogyan implementáltuk az autentikációt?"
"Milyen változtatások történtek a worker-service.ts fájlban?"
"Mutasd a legutóbbi munkát ezen a projekten"
"Mi történt, amikor hozzáadtuk a megjelenítő felületet?"
```
Részletes példákért lásd a [Keresési eszközök útmutatót](https://docs.claude-mem.ai/usage/search-tools).
---
## Béta funkciók
A Claude-Mem **béta csatornát** kínál kísérleti funkciókkal, mint az **Endless Mode** (biomimetikus memória architektúra hosszabb munkamenetekhez). Váltson a stabil és béta verziók között a webes megjelenítő felületről a http://localhost:37777 → Settings címen.
További részletekért az Endless Mode-ról és annak kipróbálásáról lásd a **[Béta funkciók dokumentációt](https://docs.claude-mem.ai/beta-features)**.
---
## Rendszerkövetelmények
- **Node.js**: 18.0.0 vagy újabb
- **Claude Code**: Legújabb verzió plugin támogatással
- **Bun**: JavaScript futtatókörnyezet és folyamatkezelő (automatikusan települ, ha hiányzik)
- **uv**: Python csomagkezelő vektor kereséshez (automatikusan települ, ha hiányzik)
- **SQLite 3**: Tartós tároláshoz (mellékelve)
---
## Konfiguráció
A beállítások a `~/.claude-mem/settings.json` fájlban kezelhetők (automatikusan létrejön alapértelmezett értékekkel az első futtatáskor). Konfigurálható az AI modell, worker port, adatkönyvtár, naplózási szint és kontextus beillesztési beállítások.
Az összes elérhető beállításért és példákért lásd a **[Konfigurációs útmutatót](https://docs.claude-mem.ai/configuration)**.
---
## Fejlesztés
Az építési utasításokért, tesztelésért és hozzájárulási munkafolyamatért lásd a **[Fejlesztési útmutatót](https://docs.claude-mem.ai/development)**.
---
## Hibaelhárítás
Problémák esetén írja le a problémát Claude-nak, és a troubleshoot skill automatikusan diagnosztizálja és javítási megoldásokat kínál.
Gyakori problémákért és megoldásokért lásd a **[Hibaelhárítási útmutatót](https://docs.claude-mem.ai/troubleshooting)**.
---
## Hibajelentések
Átfogó hibajelentések készítése az automatikus generátorral:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Hozzájárulás
A hozzájárulásokat szívesen fogadjuk! Kérjük:
1. Fork-olja a tárolót
2. Hozzon létre egy feature branchet
3. Végezze el változtatásait tesztekkel
4. Frissítse a dokumentációt
5. Nyújtson be egy Pull Requestet
A hozzájárulási munkafolyamatért lásd a [Fejlesztési útmutatót](https://docs.claude-mem.ai/development).
---
## Licenc
Ez a projekt a **GNU Affero General Public License v3.0** (AGPL-3.0) alatt licencelt.
Copyright (C) 2025 Alex Newman (@thedotmack). Minden jog fenntartva.
A teljes részletekért lásd a [LICENSE](LICENSE) fájlt.
**Mit jelent ez:**
- Szabadon használhatja, módosíthatja és terjesztheti ezt a szoftvert
- Ha módosítja és hálózati szerveren telepíti, elérhetővé kell tennie a forráskódot
- A származékos munkáknak szintén AGPL-3.0 alatt kell licencelve lenniük
- Ehhez a szoftverhez NINCS GARANCIA
**Megjegyzés a Ragtime-ról**: A `ragtime/` könyvtár külön licencelt a **PolyForm Noncommercial License 1.0.0** alatt. Részletekért lásd a [ragtime/LICENSE](ragtime/LICENSE) fájlt.
---
## Támogatás
- **Dokumentáció**: [docs/](docs/)
- **Hibák**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Tároló**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Szerző**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDK-val építve** | **Claude Code által hajtva** | **TypeScript-tel készítve**

306
.agent/services/claude-mem/docs/i18n/README.id.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 Ini adalah terjemahan otomatis. Koreksi dari komunitas sangat dipersilakan!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistem kompresi memori persisten yang dibangun untuk <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#mulai-cepat">Mulai Cepat</a> •
<a href="#cara-kerja">Cara Kerja</a> •
<a href="#alat-pencarian-mcp">Alat Pencarian</a> •
<a href="#dokumentasi">Dokumentasi</a> •
<a href="#konfigurasi">Konfigurasi</a> •
<a href="#pemecahan-masalah">Pemecahan Masalah</a> •
<a href="#lisensi">Lisensi</a>
</p>
<p align="center">
Claude-Mem secara mulus mempertahankan konteks di seluruh sesi dengan secara otomatis menangkap observasi penggunaan alat, menghasilkan ringkasan semantik, dan membuatnya tersedia untuk sesi mendatang. Ini memungkinkan Claude untuk mempertahankan kontinuitas pengetahuan tentang proyek bahkan setelah sesi berakhir atau tersambung kembali.
</p>
---
## Mulai Cepat
Mulai sesi Claude Code baru di terminal dan masukkan perintah berikut:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Restart Claude Code. Konteks dari sesi sebelumnya akan secara otomatis muncul di sesi baru.
**Fitur Utama:**
- 🧠 **Memori Persisten** - Konteks bertahan di seluruh sesi
- 📊 **Progressive Disclosure** - Pengambilan memori berlapis dengan visibilitas biaya token
- 🔍 **Pencarian Berbasis Skill** - Query riwayat proyek Anda dengan mem-search skill
- 🖥️ **Web Viewer UI** - Stream memori real-time di http://localhost:37777
- 💻 **Claude Desktop Skill** - Cari memori dari percakapan Claude Desktop
- 🔒 **Kontrol Privasi** - Gunakan tag `<private>` untuk mengecualikan konten sensitif dari penyimpanan
- ⚙️ **Konfigurasi Konteks** - Kontrol yang detail atas konteks apa yang diinjeksikan
- 🤖 **Operasi Otomatis** - Tidak memerlukan intervensi manual
- 🔗 **Kutipan** - Referensi observasi masa lalu dengan ID (akses melalui http://localhost:37777/api/observation/{id} atau lihat semua di web viewer di http://localhost:37777)
- 🧪 **Beta Channel** - Coba fitur eksperimental seperti Endless Mode melalui peralihan versi
---
## Dokumentasi
📚 **[Lihat Dokumentasi Lengkap](https://docs.claude-mem.ai/)** - Jelajahi di situs web resmi
### Memulai
- **[Panduan Instalasi](https://docs.claude-mem.ai/installation)** - Mulai cepat & instalasi lanjutan
- **[Panduan Penggunaan](https://docs.claude-mem.ai/usage/getting-started)** - Bagaimana Claude-Mem bekerja secara otomatis
- **[Alat Pencarian](https://docs.claude-mem.ai/usage/search-tools)** - Query riwayat proyek Anda dengan bahasa alami
- **[Fitur Beta](https://docs.claude-mem.ai/beta-features)** - Coba fitur eksperimental seperti Endless Mode
### Praktik Terbaik
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Prinsip optimisasi konteks agen AI
- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofi di balik strategi priming konteks Claude-Mem
### Arsitektur
- **[Ringkasan](https://docs.claude-mem.ai/architecture/overview)** - Komponen sistem & aliran data
- **[Evolusi Arsitektur](https://docs.claude-mem.ai/architecture-evolution)** - Perjalanan dari v3 ke v5
- **[Arsitektur Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Bagaimana Claude-Mem menggunakan lifecycle hooks
- **[Referensi Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 skrip hook dijelaskan
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & manajemen Bun
- **[Database](https://docs.claude-mem.ai/architecture/database)** - Skema SQLite & pencarian FTS5
- **[Arsitektur Pencarian](https://docs.claude-mem.ai/architecture/search-architecture)** - Pencarian hybrid dengan database vektor Chroma
### Konfigurasi & Pengembangan
- **[Konfigurasi](https://docs.claude-mem.ai/configuration)** - Variabel environment & pengaturan
- **[Pengembangan](https://docs.claude-mem.ai/development)** - Membangun, testing, kontribusi
- **[Pemecahan Masalah](https://docs.claude-mem.ai/troubleshooting)** - Masalah umum & solusi
---
## Cara Kerja
**Komponen Inti:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 skrip hook)
2. **Smart Install** - Pemeriksa dependensi yang di-cache (skrip pre-hook, bukan lifecycle hook)
3. **Worker Service** - HTTP API di port 37777 dengan web viewer UI dan 10 endpoint pencarian, dikelola oleh Bun
4. **SQLite Database** - Menyimpan sesi, observasi, ringkasan
5. **mem-search Skill** - Query bahasa alami dengan progressive disclosure
6. **Chroma Vector Database** - Pencarian hybrid semantik + keyword untuk pengambilan konteks yang cerdas
Lihat [Ringkasan Arsitektur](https://docs.claude-mem.ai/architecture/overview) untuk detail.
---
## mem-search Skill
Claude-Mem menyediakan pencarian cerdas melalui mem-search skill yang secara otomatis dipanggil saat Anda bertanya tentang pekerjaan masa lalu:
**Cara Kerja:**
- Tanya saja secara alami: *"Apa yang kita lakukan sesi terakhir?"* atau *"Apakah kita sudah memperbaiki bug ini sebelumnya?"*
- Claude secara otomatis memanggil mem-search skill untuk menemukan konteks yang relevan
**Operasi Pencarian yang Tersedia:**
1. **Search Observations** - Pencarian teks lengkap di seluruh observasi
2. **Search Sessions** - Pencarian teks lengkap di seluruh ringkasan sesi
3. **Search Prompts** - Cari permintaan pengguna mentah
4. **By Concept** - Temukan berdasarkan tag konsep (discovery, problem-solution, pattern, dll.)
5. **By File** - Temukan observasi yang mereferensikan file tertentu
6. **By Type** - Temukan berdasarkan tipe (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Dapatkan konteks sesi terbaru untuk sebuah proyek
8. **Timeline** - Dapatkan timeline terpadu dari konteks di sekitar titik waktu tertentu
9. **Timeline by Query** - Cari observasi dan dapatkan konteks timeline di sekitar kecocokan terbaik
10. **API Help** - Dapatkan dokumentasi API pencarian
**Contoh Query Bahasa Alami:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Lihat [Panduan Alat Pencarian](https://docs.claude-mem.ai/usage/search-tools) untuk contoh detail.
---
## Fitur Beta
Claude-Mem menawarkan **beta channel** dengan fitur eksperimental seperti **Endless Mode** (arsitektur memori biomimetik untuk sesi yang diperpanjang). Beralih antara versi stabil dan beta dari web viewer UI di http://localhost:37777 → Settings.
Lihat **[Dokumentasi Fitur Beta](https://docs.claude-mem.ai/beta-features)** untuk detail tentang Endless Mode dan cara mencobanya.
---
## Persyaratan Sistem
- **Node.js**: 18.0.0 atau lebih tinggi
- **Claude Code**: Versi terbaru dengan dukungan plugin
- **Bun**: JavaScript runtime dan process manager (otomatis diinstal jika tidak ada)
- **uv**: Python package manager untuk pencarian vektor (otomatis diinstal jika tidak ada)
- **SQLite 3**: Untuk penyimpanan persisten (terbundel)
---
## Konfigurasi
Pengaturan dikelola di `~/.claude-mem/settings.json` (otomatis dibuat dengan default saat pertama kali dijalankan). Konfigurasi model AI, port worker, direktori data, level log, dan pengaturan injeksi konteks.
Lihat **[Panduan Konfigurasi](https://docs.claude-mem.ai/configuration)** untuk semua pengaturan dan contoh yang tersedia.
---
## Pengembangan
Lihat **[Panduan Pengembangan](https://docs.claude-mem.ai/development)** untuk instruksi build, testing, dan alur kerja kontribusi.
---
## Pemecahan Masalah
Jika mengalami masalah, jelaskan masalah ke Claude dan troubleshoot skill akan secara otomatis mendiagnosis dan memberikan perbaikan.
Lihat **[Panduan Pemecahan Masalah](https://docs.claude-mem.ai/troubleshooting)** untuk masalah umum dan solusi.
---
## Laporan Bug
Buat laporan bug yang komprehensif dengan generator otomatis:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Kontribusi
Kontribusi sangat dipersilakan! Silakan:
1. Fork repositori
2. Buat branch fitur
3. Buat perubahan Anda dengan tes
4. Perbarui dokumentasi
5. Kirim Pull Request
Lihat [Panduan Pengembangan](https://docs.claude-mem.ai/development) untuk alur kerja kontribusi.
---
## Lisensi
Proyek ini dilisensikan di bawah **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
Lihat file [LICENSE](LICENSE) untuk detail lengkap.
**Apa Artinya:**
- Anda dapat menggunakan, memodifikasi, dan mendistribusikan perangkat lunak ini dengan bebas
- Jika Anda memodifikasi dan men-deploy di server jaringan, Anda harus membuat kode sumber Anda tersedia
- Karya turunan juga harus dilisensikan di bawah AGPL-3.0
- TIDAK ADA JAMINAN untuk perangkat lunak ini
**Catatan tentang Ragtime**: Direktori `ragtime/` dilisensikan secara terpisah di bawah **PolyForm Noncommercial License 1.0.0**. Lihat [ragtime/LICENSE](ragtime/LICENSE) untuk detail.
---
## Dukungan
- **Dokumentasi**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositori**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Penulis**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**
---

306
.agent/services/claude-mem/docs/i18n/README.it.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 Questa è una traduzione automatica. Le correzioni della comunità sono benvenute!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistema di compressione della memoria persistente creato per <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#avvio-rapido">Avvio Rapido</a> •
<a href="#come-funziona">Come Funziona</a> •
<a href="#strumenti-di-ricerca">Strumenti di Ricerca</a> •
<a href="#documentazione">Documentazione</a> •
<a href="#configurazione">Configurazione</a> •
<a href="#risoluzione-dei-problemi">Risoluzione dei Problemi</a> •
<a href="#licenza">Licenza</a>
</p>
<p align="center">
Claude-Mem preserva il contesto in modo fluido tra le sessioni catturando automaticamente le osservazioni sull'utilizzo degli strumenti, generando riepiloghi semantici e rendendoli disponibili per le sessioni future. Questo consente a Claude di mantenere la continuità della conoscenza sui progetti anche dopo la fine o la riconnessione delle sessioni.
</p>
---
## Avvio Rapido
Avvia una nuova sessione di Claude Code nel terminale e inserisci i seguenti comandi:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Riavvia Claude Code. Il contesto delle sessioni precedenti apparirà automaticamente nelle nuove sessioni.
**Caratteristiche Principali:**
- 🧠 **Memoria Persistente** - Il contesto sopravvive tra le sessioni
- 📊 **Divulgazione Progressiva** - Recupero della memoria a strati con visibilità del costo in token
- 🔍 **Ricerca Basata su Skill** - Interroga la cronologia del tuo progetto con la skill mem-search
- 🖥️ **Interfaccia Web Viewer** - Stream della memoria in tempo reale su http://localhost:37777
- 💻 **Skill per Claude Desktop** - Cerca nella memoria dalle conversazioni di Claude Desktop
- 🔒 **Controllo della Privacy** - Usa i tag `<private>` per escludere contenuti sensibili dall'archiviazione
- ⚙️ **Configurazione del Contesto** - Controllo granulare su quale contesto viene iniettato
- 🤖 **Funzionamento Automatico** - Nessun intervento manuale richiesto
- 🔗 **Citazioni** - Fai riferimento a osservazioni passate con ID (accedi tramite http://localhost:37777/api/observation/{id} o visualizza tutto nel web viewer su http://localhost:37777)
- 🧪 **Canale Beta** - Prova funzionalità sperimentali come Endless Mode tramite il cambio di versione
---
## Documentazione
📚 **[Visualizza Documentazione Completa](https://docs.claude-mem.ai/)** - Sfoglia sul sito ufficiale
### Per Iniziare
- **[Guida all'Installazione](https://docs.claude-mem.ai/installation)** - Avvio rapido e installazione avanzata
- **[Guida all'Uso](https://docs.claude-mem.ai/usage/getting-started)** - Come funziona automaticamente Claude-Mem
- **[Strumenti di Ricerca](https://docs.claude-mem.ai/usage/search-tools)** - Interroga la cronologia del progetto con linguaggio naturale
- **[Funzionalità Beta](https://docs.claude-mem.ai/beta-features)** - Prova funzionalità sperimentali come Endless Mode
### Best Practice
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Principi di ottimizzazione del contesto per agenti AI
- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia alla base della strategia di priming del contesto di Claude-Mem
### Architettura
- **[Panoramica](https://docs.claude-mem.ai/architecture/overview)** - Componenti del sistema e flusso dei dati
- **[Evoluzione dell'Architettura](https://docs.claude-mem.ai/architecture-evolution)** - Il percorso dalla v3 alla v5
- **[Architettura degli Hook](https://docs.claude-mem.ai/hooks-architecture)** - Come Claude-Mem utilizza gli hook del ciclo di vita
- **[Riferimento Hook](https://docs.claude-mem.ai/architecture/hooks)** - Spiegazione dei 7 script hook
- **[Servizio Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP e gestione Bun
- **[Database](https://docs.claude-mem.ai/architecture/database)** - Schema SQLite e ricerca FTS5
- **[Architettura di Ricerca](https://docs.claude-mem.ai/architecture/search-architecture)** - Ricerca ibrida con database vettoriale Chroma
### Configurazione e Sviluppo
- **[Configurazione](https://docs.claude-mem.ai/configuration)** - Variabili d'ambiente e impostazioni
- **[Sviluppo](https://docs.claude-mem.ai/development)** - Build, test e flusso di contribuzione
- **[Risoluzione dei Problemi](https://docs.claude-mem.ai/troubleshooting)** - Problemi comuni e soluzioni
---
## Come Funziona
**Componenti Principali:**
1. **5 Hook del Ciclo di Vita** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 script hook)
2. **Installazione Intelligente** - Controllo delle dipendenze in cache (script pre-hook, non un hook del ciclo di vita)
3. **Servizio Worker** - API HTTP sulla porta 37777 con interfaccia web viewer e 10 endpoint di ricerca, gestita da Bun
4. **Database SQLite** - Memorizza sessioni, osservazioni, riepiloghi
5. **Skill mem-search** - Query in linguaggio naturale con divulgazione progressiva
6. **Database Vettoriale Chroma** - Ricerca ibrida semantica + keyword per recupero intelligente del contesto
Vedi [Panoramica dell'Architettura](https://docs.claude-mem.ai/architecture/overview) per i dettagli.
---
## Skill mem-search
Claude-Mem fornisce una ricerca intelligente tramite la skill mem-search che si attiva automaticamente quando chiedi del lavoro passato:
**Come Funziona:**
- Chiedi semplicemente in modo naturale: *"Cosa abbiamo fatto nell'ultima sessione?"* o *"Abbiamo già risolto questo bug prima?"*
- Claude invoca automaticamente la skill mem-search per trovare il contesto rilevante
**Operazioni di Ricerca Disponibili:**
1. **Search Observations** - Ricerca full-text nelle osservazioni
2. **Search Sessions** - Ricerca full-text nei riepiloghi delle sessioni
3. **Search Prompts** - Ricerca nelle richieste utente grezze
4. **By Concept** - Trova per tag di concetto (discovery, problem-solution, pattern, ecc.)
5. **By File** - Trova osservazioni che fanno riferimento a file specifici
6. **By Type** - Trova per tipo (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Ottieni il contesto recente della sessione per un progetto
8. **Timeline** - Ottieni la timeline unificata del contesto attorno a un punto specifico nel tempo
9. **Timeline by Query** - Cerca osservazioni e ottieni il contesto della timeline attorno alla corrispondenza migliore
10. **API Help** - Ottieni la documentazione dell'API di ricerca
**Esempi di Query in Linguaggio Naturale:**
```
"Quali bug abbiamo risolto nell'ultima sessione?"
"Come abbiamo implementato l'autenticazione?"
"Quali modifiche sono state apportate a worker-service.ts?"
"Mostrami il lavoro recente su questo progetto"
"Cosa stava succedendo quando abbiamo aggiunto l'interfaccia del viewer?"
```
Vedi [Guida agli Strumenti di Ricerca](https://docs.claude-mem.ai/usage/search-tools) per esempi dettagliati.
---
## Funzionalità Beta
Claude-Mem offre un **canale beta** con funzionalità sperimentali come **Endless Mode** (architettura di memoria biomimetica per sessioni estese). Passa dalla versione stabile a quella beta dall'interfaccia web viewer su http://localhost:37777 → Settings.
Vedi **[Documentazione delle Funzionalità Beta](https://docs.claude-mem.ai/beta-features)** per dettagli su Endless Mode e come provarlo.
---
## Requisiti di Sistema
- **Node.js**: 18.0.0 o superiore
- **Claude Code**: Ultima versione con supporto plugin
- **Bun**: Runtime JavaScript e process manager (installato automaticamente se mancante)
- **uv**: Gestore di pacchetti Python per la ricerca vettoriale (installato automaticamente se mancante)
- **SQLite 3**: Per l'archiviazione persistente (incluso)
---
## Configurazione
Le impostazioni sono gestite in `~/.claude-mem/settings.json` (creato automaticamente con valori predefiniti alla prima esecuzione). Configura il modello AI, la porta del worker, la directory dei dati, il livello di log e le impostazioni di iniezione del contesto.
Vedi la **[Guida alla Configurazione](https://docs.claude-mem.ai/configuration)** per tutte le impostazioni disponibili ed esempi.
---
## Sviluppo
Vedi la **[Guida allo Sviluppo](https://docs.claude-mem.ai/development)** per le istruzioni di build, test e flusso di contribuzione.
---
## Risoluzione dei Problemi
Se riscontri problemi, descrivi il problema a Claude e la skill troubleshoot diagnosticherà automaticamente e fornirà correzioni.
Vedi la **[Guida alla Risoluzione dei Problemi](https://docs.claude-mem.ai/troubleshooting)** per problemi comuni e soluzioni.
---
## Segnalazione Bug
Crea report di bug completi con il generatore automatizzato:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contribuire
I contributi sono benvenuti! Per favore:
1. Fai il fork del repository
2. Crea un branch per la funzionalità
3. Apporta le tue modifiche con i test
4. Aggiorna la documentazione
5. Invia una Pull Request
Vedi [Guida allo Sviluppo](https://docs.claude-mem.ai/development) per il flusso di contribuzione.
---
## Licenza
Questo progetto è rilasciato sotto la **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Tutti i diritti riservati.
Vedi il file [LICENSE](LICENSE) per i dettagli completi.
**Cosa Significa:**
- Puoi usare, modificare e distribuire questo software liberamente
- Se modifichi e distribuisci su un server di rete, devi rendere disponibile il tuo codice sorgente
- Le opere derivate devono anche essere rilasciate sotto AGPL-3.0
- NON c'è GARANZIA per questo software
**Nota su Ragtime**: La directory `ragtime/` è rilasciata separatamente sotto la **PolyForm Noncommercial License 1.0.0**. Vedi [ragtime/LICENSE](ragtime/LICENSE) per i dettagli.
---
## Supporto
- **Documentazione**: [docs/](docs/)
- **Problemi**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autore**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Creato con Claude Agent SDK** | **Alimentato da Claude Code** | **Realizzato con TypeScript**
---

304
.agent/services/claude-mem/docs/i18n/README.ja.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 これは自動翻訳です。コミュニティによる修正を歓迎します!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center"><a href="https://claude.com/claude-code" target="_blank">Claude Code</a>向けに構築された永続的メモリ圧縮システム</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#クイックスタート">クイックスタート</a> •
<a href="#仕組み">仕組み</a> •
<a href="#mcp検索ツール">検索ツール</a> •
<a href="#ドキュメント">ドキュメント</a> •
<a href="#設定">設定</a> •
<a href="#トラブルシューティング">トラブルシューティング</a> •
<a href="#ライセンス">ライセンス</a>
</p>
<p align="center">
Claude-Memは、ツール使用の観察を自動的にキャプチャし、セマンティックサマリーを生成して将来のセッションで利用可能にすることで、セッション間のコンテキストをシームレスに保持します。これにより、Claudeはセッションが終了または再接続された後でも、プロジェクトに関する知識の連続性を維持できます。
</p>
---
## クイックスタート
ターミナルで新しいClaude Codeセッションを開始し、次のコマンドを入力します:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Claude Codeを再起動します。以前のセッションからのコンテキストが新しいセッションに自動的に表示されます。
**主な機能:**
- 🧠 **永続的メモリ** - セッション間でコンテキストが保持される
- 📊 **プログレッシブディスクロージャー** - トークンコストの可視性を持つ階層的メモリ取得
- 🔍 **スキルベース検索** - mem-searchスキルでプロジェクト履歴をクエリ
- 🖥️ **Webビューア UI** - http://localhost:37777 でリアルタイムメモリストリームを表示
- 💻 **Claude Desktopスキル** - Claude Desktopの会話からメモリを検索
- 🔒 **プライバシー制御** - `<private>`タグを使用して機密コンテンツをストレージから除外
- ⚙️ **コンテキスト設定** - どのコンテキストが注入されるかを細かく制御
- 🤖 **自動動作** - 手動介入不要
- 🔗 **引用** - IDで過去の観察を参照(http://localhost:37777/api/observation/{id} でアクセス、またはhttp://localhost:37777 のWebビューアですべて表示)
- 🧪 **ベータチャネル** - バージョン切り替えでEndless Modeなどの実験的機能を試す
---
## ドキュメント
📚 **[完全なドキュメントを見る](https://docs.claude-mem.ai/)** - 公式ウェブサイトで閲覧
### はじめに
- **[インストールガイド](https://docs.claude-mem.ai/installation)** - クイックスタートと高度なインストール
- **[使用ガイド](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Memが自動的に動作する仕組み
- **[検索ツール](https://docs.claude-mem.ai/usage/search-tools)** - 自然言語でプロジェクト履歴をクエリ
- **[ベータ機能](https://docs.claude-mem.ai/beta-features)** - Endless Modeなどの実験的機能を試す
### ベストプラクティス
- **[コンテキストエンジニアリング](https://docs.claude-mem.ai/context-engineering)** - AIエージェントのコンテキスト最適化原則
- **[プログレッシブディスクロージャー](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Memのコンテキストプライミング戦略の背後にある哲学
### アーキテクチャ
- **[概要](https://docs.claude-mem.ai/architecture/overview)** - システムコンポーネントとデータフロー
- **[アーキテクチャの進化](https://docs.claude-mem.ai/architecture-evolution)** - v3からv5への道のり
- **[フックアーキテクチャ](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Memがライフサイクルフックを使用する方法
- **[フックリファレンス](https://docs.claude-mem.ai/architecture/hooks)** - 7つのフックスクリプトの説明
- **[ワーカーサービス](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP APIとBun管理
- **[データベース](https://docs.claude-mem.ai/architecture/database)** - SQLiteスキーマとFTS5検索
- **[検索アーキテクチャ](https://docs.claude-mem.ai/architecture/search-architecture)** - Chromaベクトルデータベースを使用したハイブリッド検索
### 設定と開発
- **[設定](https://docs.claude-mem.ai/configuration)** - 環境変数と設定
- **[開発](https://docs.claude-mem.ai/development)** - ビルド、テスト、コントリビューション
- **[トラブルシューティング](https://docs.claude-mem.ai/troubleshooting)** - よくある問題と解決策
---
## 仕組み
**コアコンポーネント:**
1. **5つのライフサイクルフック** - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd(6つのフックスクリプト)
2. **スマートインストール** - キャッシュされた依存関係チェッカー(プレフックスクリプト、ライフサイクルフックではない)
3. **ワーカーサービス** - ポート37777上のHTTP API、WebビューアUIと10の検索エンドポイント、Bunで管理
4. **SQLiteデータベース** - セッション、観察、サマリーを保存
5. **mem-searchスキル** - プログレッシブディスクロージャーを備えた自然言語クエリ
6. **Chromaベクトルデータベース** - インテリジェントなコンテキスト取得のためのハイブリッドセマンティック+キーワード検索
詳細は[アーキテクチャ概要](https://docs.claude-mem.ai/architecture/overview)を参照してください。
---
## mem-searchスキル
Claude-Memは、過去の作業について尋ねると自動的に呼び出されるmem-searchスキルを通じてインテリジェント検索を提供します:
**仕組み:**
- 自然に質問するだけ: *「前回のセッションで何をしましたか?」* または *「以前このバグを修正しましたか?」*
- Claudeは自動的にmem-searchスキルを呼び出して関連するコンテキストを検索します
**利用可能な検索操作:**
1. **観察の検索** - 観察全体にわたる全文検索
2. **セッションの検索** - セッションサマリー全体にわたる全文検索
3. **プロンプトの検索** - 生のユーザーリクエストを検索
4. **コンセプト別** - コンセプトタグで検索(discovery、problem-solution、patternなど)
5. **ファイル別** - 特定のファイルを参照している観察を検索
6. **タイプ別** - タイプ別に検索(decision、bugfix、feature、refactor、discovery、change)
7. **最近のコンテキスト** - プロジェクトの最近のセッションコンテキストを取得
8. **タイムライン** - 特定の時点周辺のコンテキストの統一タイムラインを取得
9. **クエリ別タイムライン** - 観察を検索し、最適な一致周辺のタイムラインコンテキストを取得
10. **APIヘルプ** - 検索APIドキュメントを取得
**自然言語クエリの例:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
詳細な例は[検索ツールガイド](https://docs.claude-mem.ai/usage/search-tools)を参照してください。
---
## ベータ機能
Claude-Memは、**Endless Mode**(拡張セッション用の生体模倣メモリアーキテクチャ)などの実験的機能を備えた**ベータチャネル**を提供します。http://localhost:37777 → SettingsのWebビューアUIから安定版とベータ版を切り替えます。
Endless Modeと試用方法の詳細については、**[ベータ機能ドキュメント](https://docs.claude-mem.ai/beta-features)** を参照してください。
---
## システム要件
- **Node.js**: 18.0.0以上
- **Claude Code**: プラグインサポートを備えた最新バージョン
- **Bun**: JavaScriptランタイムおよびプロセスマネージャー(不足している場合は自動インストール)
- **uv**: ベクトル検索用のPythonパッケージマネージャー(不足している場合は自動インストール)
- **SQLite 3**: 永続ストレージ用(バンドル済み)
---
## 設定
設定は`~/.claude-mem/settings.json`で管理されます(初回実行時にデフォルト値で自動作成)。AIモデル、ワーカーポート、データディレクトリ、ログレベル、コンテキスト注入設定を構成します。
利用可能なすべての設定と例については、**[設定ガイド](https://docs.claude-mem.ai/configuration)** を参照してください。
---
## 開発
ビルド手順、テスト、コントリビューションワークフローについては、**[開発ガイド](https://docs.claude-mem.ai/development)** を参照してください。
---
## トラブルシューティング
問題が発生した場合は、Claudeに問題を説明すると、troubleshootスキルが自動的に診断して修正を提供します。
よくある問題と解決策については、**[トラブルシューティングガイド](https://docs.claude-mem.ai/troubleshooting)** を参照してください。
---
## バグレポート
自動ジェネレーターで包括的なバグレポートを作成します:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## コントリビューション
コントリビューションを歓迎します! 以下の手順に従ってください:
1. リポジトリをフォーク
2. 機能ブランチを作成
3. テストと共に変更を加える
4. ドキュメントを更新
5. プルリクエストを提出
コントリビューションワークフローについては[開発ガイド](https://docs.claude-mem.ai/development)を参照してください。
---
## ライセンス
このプロジェクトは**GNU Affero General Public License v3.0**(AGPL-3.0)の下でライセンスされています。
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
詳細は[LICENSE](LICENSE)ファイルを参照してください。
**これが意味すること:**
- このソフトウェアを自由に使用、変更、配布できます
- ネットワークサーバーで変更して展開する場合、ソースコードを利用可能にする必要があります
- 派生作品もAGPL-3.0の下でライセンスする必要があります
- このソフトウェアには保証がありません
**Ragtimeに関する注意**: `ragtime/`ディレクトリは **PolyForm Noncommercial License 1.0.0** の下で個別にライセンスされています。詳細は[ragtime/LICENSE](ragtime/LICENSE)を参照してください。
---
## サポート
- **ドキュメント**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **リポジトリ**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **作者**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDKで構築** | **Claude Codeで動作** | **TypeScriptで作成**

306
.agent/services/claude-mem/docs/i18n/README.ko.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 이것은 자동 번역입니다. 커뮤니티의 수정 제안을 환영합니다!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center"><a href="https://claude.com/claude-code" target="_blank">Claude Code</a>를 위해 구축된 지속적인 메모리 압축 시스템.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#빠른-시작">빠른 시작</a> •
<a href="#작동-방식">작동 방식</a> •
<a href="#mcp-검색-도구">검색 도구</a> •
<a href="#문서">문서</a> •
<a href="#설정">설정</a> •
<a href="#문제-해결">문제 해결</a> •
<a href="#라이선스">라이선스</a>
</p>
<p align="center">
Claude-Mem은 도구 사용 관찰을 자동으로 캡처하고 의미론적 요약을 생성하여 향후 세션에서 사용할 수 있도록 함으로써 세션 간 컨텍스트를 원활하게 보존합니다. 이를 통해 Claude는 세션이 종료되거나 재연결된 후에도 프로젝트에 대한 지식의 연속성을 유지할 수 있습니다.
</p>
---
## 빠른 시작
터미널에서 새 Claude Code 세션을 시작하고 다음 명령을 입력하세요:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Claude Code를 재시작하세요. 이전 세션의 컨텍스트가 자동으로 새 세션에 나타납니다.
**주요 기능:**
- 🧠 **지속적인 메모리** - 세션 간 컨텍스트 유지
- 📊 **점진적 공개** - 토큰 비용 가시성을 갖춘 계층화된 메모리 검색
- 🔍 **스킬 기반 검색** - mem-search 스킬로 프로젝트 기록 쿼리
- 🖥️ **웹 뷰어 UI** - http://localhost:37777 에서 실시간 메모리 스트림 확인
- 💻 **Claude Desktop 스킬** - Claude Desktop 대화에서 메모리 검색
- 🔒 **개인정보 제어** - `<private>` 태그를 사용하여 민감한 콘텐츠를 저장소에서 제외
- ⚙️ **컨텍스트 설정** - 주입되는 컨텍스트에 대한 세밀한 제어
- 🤖 **자동 작동** - 수동 개입 불필요
- 🔗 **인용** - ID로 과거 관찰 참조 (http://localhost:37777/api/observation/{id} 를 통해 액세스하거나 http://localhost:37777 의 웹 뷰어에서 모두 보기)
- 🧪 **베타 채널** - 버전 전환을 통해 Endless Mode와 같은 실험적 기능 사용
---
## 문서
📚 **[전체 문서 보기](https://docs.claude-mem.ai/)** - 공식 웹사이트에서 찾아보기
### 시작하기
- **[설치 가이드](https://docs.claude-mem.ai/installation)** - 빠른 시작 및 고급 설치
- **[사용 가이드](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem이 자동으로 작동하는 방법
- **[검색 도구](https://docs.claude-mem.ai/usage/search-tools)** - 자연어로 프로젝트 기록 쿼리
- **[베타 기능](https://docs.claude-mem.ai/beta-features)** - Endless Mode와 같은 실험적 기능 시도
### 모범 사례
- **[컨텍스트 엔지니어링](https://docs.claude-mem.ai/context-engineering)** - AI 에이전트 컨텍스트 최적화 원칙
- **[점진적 공개](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem의 컨텍스트 프라이밍 전략의 철학
### 아키텍처
- **[개요](https://docs.claude-mem.ai/architecture/overview)** - 시스템 구성 요소 및 데이터 흐름
- **[아키텍처 진화](https://docs.claude-mem.ai/architecture-evolution)** - v3에서 v5로의 여정
- **[후크 아키텍처](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem이 라이프사이클 후크를 사용하는 방법
- **[후크 참조](https://docs.claude-mem.ai/architecture/hooks)** - 7개 후크 스크립트 설명
- **[워커 서비스](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API 및 Bun 관리
- **[데이터베이스](https://docs.claude-mem.ai/architecture/database)** - SQLite 스키마 및 FTS5 검색
- **[검색 아키텍처](https://docs.claude-mem.ai/architecture/search-architecture)** - Chroma 벡터 데이터베이스를 활용한 하이브리드 검색
### 설정 및 개발
- **[설정](https://docs.claude-mem.ai/configuration)** - 환경 변수 및 설정
- **[개발](https://docs.claude-mem.ai/development)** - 빌드, 테스트, 기여
- **[문제 해결](https://docs.claude-mem.ai/troubleshooting)** - 일반적인 문제 및 해결 방법
---
## 작동 방식
**핵심 구성 요소:**
1. **5개 라이프사이클 후크** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6개 후크 스크립트)
2. **스마트 설치** - 캐시된 종속성 검사기 (사전 후크 스크립트, 라이프사이클 후크 아님)
3. **워커 서비스** - 웹 뷰어 UI와 10개 검색 엔드포인트를 갖춘 포트 37777의 HTTP API, Bun으로 관리
4. **SQLite 데이터베이스** - 세션, 관찰, 요약 저장
5. **mem-search 스킬** - 점진적 공개를 통한 자연어 쿼리
6. **Chroma 벡터 데이터베이스** - 지능형 컨텍스트 검색을 위한 하이브리드 의미론적 + 키워드 검색
자세한 내용은 [아키텍처 개요](https://docs.claude-mem.ai/architecture/overview)를 참조하세요.
---
## mem-search 스킬
Claude-Mem은 과거 작업에 대해 질문할 때 자동으로 호출되는 mem-search 스킬을 통해 지능형 검색을 제공합니다:
**작동 방식:**
- 자연스럽게 질문하세요: *"지난 세션에서 무엇을 했나요?"* 또는 *"이 버그를 이전에 수정했나요?"*
- Claude가 관련 컨텍스트를 찾기 위해 mem-search 스킬을 자동으로 호출합니다
**사용 가능한 검색 작업:**
1. **관찰 검색** - 관찰에 대한 전체 텍스트 검색
2. **세션 검색** - 세션 요약에 대한 전체 텍스트 검색
3. **프롬프트 검색** - 원시 사용자 요청 검색
4. **개념별** - 개념 태그로 찾기 (discovery, problem-solution, pattern 등)
5. **파일별** - 특정 파일을 참조하는 관찰 찾기
6. **유형별** - 유형별로 찾기 (decision, bugfix, feature, refactor, discovery, change)
7. **최근 컨텍스트** - 프로젝트의 최근 세션 컨텍스트 가져오기
8. **타임라인** - 특정 시점 주변의 통합된 컨텍스트 타임라인 가져오기
9. **쿼리별 타임라인** - 관찰을 검색하고 가장 일치하는 항목 주변의 타임라인 컨텍스트 가져오기
10. **API 도움말** - 검색 API 문서 가져오기
**자연어 쿼리 예제:**
```
"지난 세션에서 어떤 버그를 수정했나요?"
"인증을 어떻게 구현했나요?"
"worker-service.ts에 어떤 변경 사항이 있었나요?"
"이 프로젝트의 최근 작업을 보여주세요"
"뷰어 UI를 추가할 때 무슨 일이 있었나요?"
```
자세한 예제는 [검색 도구 가이드](https://docs.claude-mem.ai/usage/search-tools)를 참조하세요.
---
## 베타 기능
Claude-Mem은 **Endless Mode**(확장된 세션을 위한 생체모방 메모리 아키텍처)와 같은 실험적 기능을 제공하는 **베타 채널**을 제공합니다. http://localhost:37777 → Settings의 웹 뷰어 UI에서 안정 버전과 베타 버전 간 전환이 가능합니다.
Endless Mode 및 사용 방법에 대한 자세한 내용은 **[베타 기능 문서](https://docs.claude-mem.ai/beta-features)**를 참조하세요.
---
## 시스템 요구 사항
- **Node.js**: 18.0.0 이상
- **Claude Code**: 플러그인 지원이 있는 최신 버전
- **Bun**: JavaScript 런타임 및 프로세스 관리자 (누락 시 자동 설치)
- **uv**: 벡터 검색을 위한 Python 패키지 관리자 (누락 시 자동 설치)
- **SQLite 3**: 영구 저장을 위한 데이터베이스 (번들 포함)
---
## 설정
설정은 `~/.claude-mem/settings.json`에서 관리됩니다 (첫 실행 시 기본값으로 자동 생성). AI 모델, 워커 포트, 데이터 디렉토리, 로그 수준 및 컨텍스트 주입 설정을 구성할 수 있습니다.
사용 가능한 모든 설정 및 예제는 **[설정 가이드](https://docs.claude-mem.ai/configuration)**를 참조하세요.
---
## 개발
빌드 지침, 테스트 및 기여 워크플로우는 **[개발 가이드](https://docs.claude-mem.ai/development)**를 참조하세요.
---
## 문제 해결
문제가 발생하면 Claude에게 문제를 설명하면 troubleshoot 스킬이 자동으로 진단하고 수정 사항을 제공합니다.
일반적인 문제 및 해결 방법은 **[문제 해결 가이드](https://docs.claude-mem.ai/troubleshooting)**를 참조하세요.
---
## 버그 보고
자동화된 생성기로 포괄적인 버그 보고서를 작성하세요:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## 기여
기여를 환영합니다! 다음 절차를 따라주세요:
1. 저장소 포크
2. 기능 브랜치 생성
3. 테스트와 함께 변경 사항 작성
4. 문서 업데이트
5. Pull Request 제출
기여 워크플로우는 [개발 가이드](https://docs.claude-mem.ai/development)를 참조하세요.
---
## 라이선스
이 프로젝트는 **GNU Affero General Public License v3.0** (AGPL-3.0)에 따라 라이선스가 부여됩니다.
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
전체 세부 정보는 [LICENSE](LICENSE) 파일을 참조하세요.
**의미:**
- 이 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다
- 수정하여 네트워크 서버에 배포하는 경우 소스 코드를 공개해야 합니다
- 파생 작업물도 AGPL-3.0에 따라 라이선스가 부여되어야 합니다
- 이 소프트웨어에는 보증이 없습니다
**Ragtime에 대한 참고 사항**: `ragtime/` 디렉토리는 **PolyForm Noncommercial License 1.0.0**에 따라 별도로 라이선스가 부여됩니다. 자세한 내용은 [ragtime/LICENSE](ragtime/LICENSE)를 참조하세요.
---
## 지원
- **문서**: [docs/](docs/)
- **이슈**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **저장소**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **작성자**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDK로 구축** | **Claude Code 기반** | **TypeScript로 제작**
---

303
.agent/services/claude-mem/docs/i18n/README.nl.md Normal file
View File

@@ -0,0 +1,303 @@
🌐 Dit is een automatische vertaling. Gemeenschapscorrecties zijn welkom!
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Persistent geheugencompressiesysteem gebouwd voor <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#snel-starten">Snel Starten</a> •
<a href="#hoe-het-werkt">Hoe Het Werkt</a> •
<a href="#zoektools">Zoektools</a> •
<a href="#documentatie">Documentatie</a> •
<a href="#configuratie">Configuratie</a> •
<a href="#probleemoplossing">Probleemoplossing</a> •
<a href="#licentie">Licentie</a>
</p>
<p align="center">
Claude-Mem behoudt naadloos context tussen sessies door automatisch waarnemingen van toolgebruik vast te leggen, semantische samenvattingen te genereren en deze beschikbaar te maken voor toekomstige sessies. Dit stelt Claude in staat om continuïteit van kennis over projecten te behouden, zelfs nadat sessies eindigen of opnieuw verbinden.
</p>
---
## Snel Starten
Start een nieuwe Claude Code sessie in de terminal en voer de volgende commando's in:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Herstart Claude Code. Context van eerdere sessies verschijnt automatisch in nieuwe sessies.
**Belangrijkste Functies:**
- 🧠 **Persistent Geheugen** - Context blijft behouden tussen sessies
- 📊 **Progressieve Onthulling** - Gelaagde geheugenophaling met zichtbaarheid van tokenkosten
- 🔍 **Vaardigheidgebaseerd Zoeken** - Bevraag je projectgeschiedenis met mem-search vaardigheid
- 🖥️ **Web Viewer UI** - Real-time geheugenstroom op http://localhost:37777
- 💻 **Claude Desktop Vaardigheid** - Zoek geheugen vanuit Claude Desktop gesprekken
- 🔒 **Privacycontrole** - Gebruik `<private>` tags om gevoelige content uit te sluiten van opslag
- ⚙️ **Context Configuratie** - Fijnmazige controle over welke context wordt geïnjecteerd
- 🤖 **Automatische Werking** - Geen handmatige tussenkomst vereist
- 🔗 **Citaten** - Verwijs naar eerdere waarnemingen met ID's (toegang via http://localhost:37777/api/observation/{id} of bekijk alle in de web viewer op http://localhost:37777)
- 🧪 **Bètakanaal** - Probeer experimentele functies zoals Endless Mode via versieschakeling
---
## Documentatie
📚 **[Bekijk Volledige Documentatie](https://docs.claude-mem.ai/)** - Bladeren op de officiële website
### Aan de Slag
- **[Installatiegids](https://docs.claude-mem.ai/installation)** - Snel starten & geavanceerde installatie
- **[Gebruikersgids](https://docs.claude-mem.ai/usage/getting-started)** - Hoe Claude-Mem automatisch werkt
- **[Zoektools](https://docs.claude-mem.ai/usage/search-tools)** - Bevraag je projectgeschiedenis met natuurlijke taal
- **[Bètafuncties](https://docs.claude-mem.ai/beta-features)** - Probeer experimentele functies zoals Endless Mode
### Beste Praktijken
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI agent context optimalisatieprincipes
- **[Progressieve Onthulling](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofie achter Claude-Mem's context priming strategie
### Architectuur
- **[Overzicht](https://docs.claude-mem.ai/architecture/overview)** - Systeemcomponenten & gegevensstroom
- **[Architectuurevolutie](https://docs.claude-mem.ai/architecture-evolution)** - De reis van v3 naar v5
- **[Hooks Architectuur](https://docs.claude-mem.ai/hooks-architecture)** - Hoe Claude-Mem lifecycle hooks gebruikt
- **[Hooks Referentie](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts uitgelegd
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun beheer
- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 zoeken
- **[Zoekarchitectuur](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybride zoeken met Chroma vector database
### Configuratie & Ontwikkeling
- **[Configuratie](https://docs.claude-mem.ai/configuration)** - Omgevingsvariabelen & instellingen
- **[Ontwikkeling](https://docs.claude-mem.ai/development)** - Bouwen, testen, bijdragen
- **[Probleemoplossing](https://docs.claude-mem.ai/troubleshooting)** - Veelvoorkomende problemen & oplossingen
---
## Hoe Het Werkt
**Kerncomponenten:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. **Slimme Installatie** - Gecachte afhankelijkheidscontrole (pre-hook script, geen lifecycle hook)
3. **Worker Service** - HTTP API op poort 37777 met web viewer UI en 10 zoekeindpunten, beheerd door Bun
4. **SQLite Database** - Slaat sessies, waarnemingen, samenvattingen op
5. **mem-search Vaardigheid** - Natuurlijke taal queries met progressieve onthulling
6. **Chroma Vector Database** - Hybride semantisch + zoekwoord zoeken voor intelligente context ophaling
Zie [Architectuuroverzicht](https://docs.claude-mem.ai/architecture/overview) voor details.
---
## mem-search Vaardigheid
Claude-Mem biedt intelligent zoeken via de mem-search vaardigheid die automatisch wordt aangeroepen wanneer je vraagt over eerder werk:
**Hoe Het Werkt:**
- Vraag gewoon natuurlijk: *"Wat hebben we vorige sessie gedaan?"* of *"Hebben we deze bug eerder opgelost?"*
- Claude roept automatisch de mem-search vaardigheid aan om relevante context te vinden
**Beschikbare Zoekoperaties:**
1. **Search Observations** - Volledige tekst zoeken door waarnemingen
2. **Search Sessions** - Volledige tekst zoeken door sessiesamenvattingen
3. **Search Prompts** - Zoek ruwe gebruikersverzoeken
4. **By Concept** - Vind op concepttags (discovery, problem-solution, pattern, etc.)
5. **By File** - Vind waarnemingen die specifieke bestanden refereren
6. **By Type** - Vind op type (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Krijg recente sessiecontext voor een project
8. **Timeline** - Krijg uniforme tijdlijn van context rond een specifiek tijdstip
9. **Timeline by Query** - Zoek naar waarnemingen en krijg tijdlijncontext rond beste match
10. **API Help** - Krijg zoek API documentatie
**Voorbeeld Natuurlijke Taal Queries:**
```
"Welke bugs hebben we vorige sessie opgelost?"
"Hoe hebben we authenticatie geïmplementeerd?"
"Welke wijzigingen zijn gemaakt aan worker-service.ts?"
"Laat me recent werk aan dit project zien"
"Wat gebeurde er toen we de viewer UI toevoegden?"
```
Zie [Zoektools Gids](https://docs.claude-mem.ai/usage/search-tools) voor gedetailleerde voorbeelden.
---
## Bètafuncties
Claude-Mem biedt een **bètakanaal** met experimentele functies zoals **Endless Mode** (biomimetische geheugenarchitectuur voor uitgebreide sessies). Schakel tussen stabiele en bètaversies vanuit de web viewer UI op http://localhost:37777 → Settings.
Zie **[Bètafuncties Documentatie](https://docs.claude-mem.ai/beta-features)** voor details over Endless Mode en hoe je het kunt proberen.
---
## Systeemvereisten
- **Node.js**: 18.0.0 of hoger
- **Claude Code**: Nieuwste versie met plugin ondersteuning
- **Bun**: JavaScript runtime en procesbeheer (automatisch geïnstalleerd indien ontbreekt)
- **uv**: Python package manager voor vector zoeken (automatisch geïnstalleerd indien ontbreekt)
- **SQLite 3**: Voor persistente opslag (meegeleverd)
---
## Configuratie
Instellingen worden beheerd in `~/.claude-mem/settings.json` (automatisch aangemaakt met standaardinstellingen bij eerste run). Configureer AI model, worker poort, data directory, logniveau en context injectie-instellingen.
Zie de **[Configuratiegids](https://docs.claude-mem.ai/configuration)** voor alle beschikbare instellingen en voorbeelden.
---
## Ontwikkeling
Zie de **[Ontwikkelingsgids](https://docs.claude-mem.ai/development)** voor bouwinstructies, testen en bijdrageworkflow.
---
## Probleemoplossing
Als je problemen ervaart, beschrijf het probleem aan Claude en de troubleshoot vaardigheid zal automatisch diagnosticeren en oplossingen bieden.
Zie de **[Probleemoplossingsgids](https://docs.claude-mem.ai/troubleshooting)** voor veelvoorkomende problemen en oplossingen.
---
## Bugrapporten
Maak uitgebreide bugrapporten met de geautomatiseerde generator:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Bijdragen
Bijdragen zijn welkom! Gelieve:
1. Fork de repository
2. Maak een feature branch
3. Maak je wijzigingen met tests
4. Update documentatie
5. Dien een Pull Request in
Zie [Ontwikkelingsgids](https://docs.claude-mem.ai/development) voor bijdrageworkflow.
---
## Licentie
Dit project is gelicentieerd onder de **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Alle rechten voorbehouden.
Zie het [LICENSE](LICENSE) bestand voor volledige details.
**Wat Dit Betekent:**
- Je kunt deze software vrijelijk gebruiken, aanpassen en distribueren
- Als je aanpast en implementeert op een netwerkserver, moet je je broncode beschikbaar maken
- Afgeleide werken moeten ook gelicentieerd zijn onder AGPL-3.0
- Er is GEEN GARANTIE voor deze software
**Opmerking over Ragtime**: De `ragtime/` directory is afzonderlijk gelicentieerd onder de **PolyForm Noncommercial License 1.0.0**. Zie [ragtime/LICENSE](ragtime/LICENSE) voor details.
---
## Ondersteuning
- **Documentatie**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Auteur**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Gebouwd met Claude Agent SDK** | **Aangedreven door Claude Code** | **Gemaakt met TypeScript**

306
.agent/services/claude-mem/docs/i18n/README.no.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 Dette er en automatisk oversettelse. Bidrag fra fellesskapet er velkomne!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Vedvarende minnekomprimeringssystem bygget for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#hurtigstart">Hurtigstart</a> •
<a href="#hvordan-det-fungerer">Hvordan Det Fungerer</a> •
<a href="#mcp-søkeverktøy">Søkeverktøy</a> •
<a href="#dokumentasjon">Dokumentasjon</a> •
<a href="#konfigurasjon">Konfigurasjon</a> •
<a href="#feilsøking">Feilsøking</a> •
<a href="#lisens">Lisens</a>
</p>
<p align="center">
Claude-Mem bevarer sømløst kontekst på tvers av økter ved automatisk å fange opp observasjoner av verktøybruk, generere semantiske sammendrag, og gjøre dem tilgjengelige for fremtidige økter. Dette gjør det mulig for Claude å opprettholde kunnskapskontinuitet om prosjekter selv etter at økter avsluttes eller gjenopprettes.
</p>
---
## Hurtigstart
Start en ny Claude Code-økt i terminalen og skriv inn følgende kommandoer:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Start Claude Code på nytt. Kontekst fra tidligere økter vil automatisk vises i nye økter.
**Nøkkelfunksjoner:**
- 🧠 **Vedvarende Minne** - Kontekst overlever på tvers av økter
- 📊 **Progressiv Avsløring** - Lagdelt minnehenting med synlighet av tokenkostnader
- 🔍 **Ferdighetsbasert Søk** - Spør om prosjekthistorikken din med mem-search-ferdigheten
- 🖥️ **Nettleser UI** - Sanntids minnestrøm på http://localhost:37777
- 💻 **Claude Desktop-ferdighet** - Søk i minne fra Claude Desktop-samtaler
- 🔒 **Personvernkontroll** - Bruk `<private>`-tagger for å ekskludere sensitivt innhold fra lagring
- ⚙️ **Kontekstkonfigurasjon** - Finjustert kontroll over hvilken kontekst som injiseres
- 🤖 **Automatisk Drift** - Ingen manuell inngripen nødvendig
- 🔗 **Kildehenvisninger** - Referer til tidligere observasjoner med ID-er (tilgang via http://localhost:37777/api/observation/{id} eller se alle i nettviseren på http://localhost:37777)
- 🧪 **Beta-kanal** - Prøv eksperimentelle funksjoner som Endless Mode via versjonsbytte
---
## Dokumentasjon
📚 **[Se Full Dokumentasjon](https://docs.claude-mem.ai/)** - Bla gjennom på det offisielle nettstedet
### Komme I Gang
- **[Installasjonsveiledning](https://docs.claude-mem.ai/installation)** - Hurtigstart og avansert installasjon
- **[Brukerveiledning](https://docs.claude-mem.ai/usage/getting-started)** - Hvordan Claude-Mem fungerer automatisk
- **[Søkeverktøy](https://docs.claude-mem.ai/usage/search-tools)** - Spør om prosjekthistorikken din med naturlig språk
- **[Beta-funksjoner](https://docs.claude-mem.ai/beta-features)** - Prøv eksperimentelle funksjoner som Endless Mode
### Beste Praksis
- **[Kontekst Engineering](https://docs.claude-mem.ai/context-engineering)** - Optimaliseringsprinsipper for AI-agentkontekst
- **[Progressiv Avsløring](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofien bak Claude-Mems strategi for kontekstpriming
### Arkitektur
- **[Oversikt](https://docs.claude-mem.ai/architecture/overview)** - Systemkomponenter og dataflyt
- **[Arkitekturutvikling](https://docs.claude-mem.ai/architecture-evolution)** - Reisen fra v3 til v5
- **[Hooks-arkitektur](https://docs.claude-mem.ai/hooks-architecture)** - Hvordan Claude-Mem bruker livssyklus-hooks
- **[Hooks-referanse](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook-skript forklart
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API og Bun-administrasjon
- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite-skjema og FTS5-søk
- **[Søkearkitektur](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybridsøk med Chroma vektordatabase
### Konfigurasjon og Utvikling
- **[Konfigurasjon](https://docs.claude-mem.ai/configuration)** - Miljøvariabler og innstillinger
- **[Utvikling](https://docs.claude-mem.ai/development)** - Bygging, testing, bidragsflyt
- **[Feilsøking](https://docs.claude-mem.ai/troubleshooting)** - Vanlige problemer og løsninger
---
## Hvordan Det Fungerer
**Kjernekomponenter:**
1. **5 Livssyklus-Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook-skript)
2. **Smart Installasjon** - Bufret avhengighetssjekker (pre-hook-skript, ikke en livssyklus-hook)
3. **Worker Service** - HTTP API på port 37777 med nettleser UI og 10 søkeendepunkter, administrert av Bun
4. **SQLite Database** - Lagrer økter, observasjoner, sammendrag
5. **mem-search-ferdighet** - Naturligspråklige spørringer med progressiv avsløring
6. **Chroma Vektordatabase** - Hybrid semantisk + nøkkelordsøk for intelligent konteksthenting
Se [Arkitekturoversikt](https://docs.claude-mem.ai/architecture/overview) for detaljer.
---
## mem-search-ferdighet
Claude-Mem tilbyr intelligent søk gjennom mem-search-ferdigheten som automatisk aktiveres når du spør om tidligere arbeid:
**Hvordan Det Fungerer:**
- Bare spør naturlig: *"Hva gjorde vi forrige økt?"* eller *"Fikset vi denne feilen før?"*
- Claude aktiverer automatisk mem-search-ferdigheten for å finne relevant kontekst
**Tilgjengelige Søkeoperasjoner:**
1. **Search Observations** - Fulltekstsøk på tvers av observasjoner
2. **Search Sessions** - Fulltekstsøk på tvers av øktsammendrag
3. **Search Prompts** - Søk i rå brukerforespørsler
4. **By Concept** - Finn etter konsept-tagger (discovery, problem-solution, pattern, osv.)
5. **By File** - Finn observasjoner som refererer til spesifikke filer
6. **By Type** - Finn etter type (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Få nylig øktkontekst for et prosjekt
8. **Timeline** - Få samlet tidslinje av kontekst rundt et spesifikt tidspunkt
9. **Timeline by Query** - Søk etter observasjoner og få tidslinjekontekst rundt beste treff
10. **API Help** - Få søke-API-dokumentasjon
**Eksempel på Naturligspråklige Spørringer:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Se [Søkeverktøy-veiledning](https://docs.claude-mem.ai/usage/search-tools) for detaljerte eksempler.
---
## Beta-funksjoner
Claude-Mem tilbyr en **beta-kanal** med eksperimentelle funksjoner som **Endless Mode** (biomimetisk minnearkitektur for utvidede økter). Bytt mellom stabile og beta-versjoner fra nettleser-UI på http://localhost:37777 → Settings.
Se **[Beta-funksjoner Dokumentasjon](https://docs.claude-mem.ai/beta-features)** for detaljer om Endless Mode og hvordan du prøver det.
---
## Systemkrav
- **Node.js**: 18.0.0 eller høyere
- **Claude Code**: Nyeste versjon med plugin-støtte
- **Bun**: JavaScript-runtime og prosessadministrator (autoinstalleres hvis mangler)
- **uv**: Python-pakkeadministrator for vektorsøk (autoinstalleres hvis mangler)
- **SQLite 3**: For vedvarende lagring (inkludert)
---
## Konfigurasjon
Innstillinger administreres i `~/.claude-mem/settings.json` (opprettes automatisk med standardverdier ved første kjøring). Konfigurer AI-modell, worker-port, datakatalog, loggnivå og innstillinger for kontekstinjeksjon.
Se **[Konfigurasjonsveiledning](https://docs.claude-mem.ai/configuration)** for alle tilgjengelige innstillinger og eksempler.
---
## Utvikling
Se **[Utviklingsveiledning](https://docs.claude-mem.ai/development)** for byggeinstruksjoner, testing og bidragsflyt.
---
## Feilsøking
Hvis du opplever problemer, beskriv problemet til Claude og troubleshoot-ferdigheten vil automatisk diagnostisere og gi løsninger.
Se **[Feilsøkingsveiledning](https://docs.claude-mem.ai/troubleshooting)** for vanlige problemer og løsninger.
---
## Feilrapporter
Opprett omfattende feilrapporter med den automatiserte generatoren:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Bidra
Bidrag er velkomne! Vennligst:
1. Fork repositoryet
2. Opprett en feature-gren
3. Gjør endringene dine med tester
4. Oppdater dokumentasjonen
5. Send inn en Pull Request
Se [Utviklingsveiledning](https://docs.claude-mem.ai/development) for bidragsflyt.
---
## Lisens
Dette prosjektet er lisensiert under **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Alle rettigheter reservert.
Se [LICENSE](LICENSE)-filen for fullstendige detaljer.
**Hva Dette Betyr:**
- Du kan bruke, modifisere og distribuere denne programvaren fritt
- Hvis du modifiserer og distribuerer på en nettverkstjener, må du gjøre kildekoden din tilgjengelig
- Avledede verk må også være lisensiert under AGPL-3.0
- Det er INGEN GARANTI for denne programvaren
**Merknad om Ragtime**: `ragtime/`-katalogen er lisensiert separat under **PolyForm Noncommercial License 1.0.0**. Se [ragtime/LICENSE](ragtime/LICENSE) for detaljer.
---
## Støtte
- **Dokumentasjon**: [docs/](docs/)
- **Problemer**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Forfatter**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Bygget med Claude Agent SDK** | **Drevet av Claude Code** | **Laget med TypeScript**
---

303
.agent/services/claude-mem/docs/i18n/README.pl.md Normal file
View File

@@ -0,0 +1,303 @@
🌐 To jest automatyczne tłumaczenie. Korekty społeczności są mile widziane!
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">System trwałej kompresji pamięci stworzony dla <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#szybki-start">Szybki Start</a> •
<a href="#jak-to-działa">Jak To Działa</a> •
<a href="#narzędzia-wyszukiwania">Narzędzia Wyszukiwania</a> •
<a href="#dokumentacja">Dokumentacja</a> •
<a href="#konfiguracja">Konfiguracja</a> •
<a href="#rozwiązywanie-problemów">Rozwiązywanie Problemów</a> •
<a href="#licencja">Licencja</a>
</p>
<p align="center">
Claude-Mem płynnie zachowuje kontekst między sesjami, automatycznie przechwytując obserwacje użycia narzędzi, generując semantyczne podsumowania i udostępniając je przyszłym sesjom. To umożliwia Claude utrzymanie ciągłości wiedzy o projektach nawet po zakończeniu lub ponownym połączeniu sesji.
</p>
---
## Szybki Start
Uruchom nową sesję Claude Code w terminalu i wprowadź następujące polecenia:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Uruchom ponownie Claude Code. Kontekst z poprzednich sesji automatycznie pojawi się w nowych sesjach.
**Kluczowe Funkcje:**
- 🧠 **Trwała Pamięć** - Kontekst przetrwa między sesjami
- 📊 **Stopniowe Ujawnianie** - Warstwowe pobieranie pamięci z widocznością kosztów tokenów
- 🔍 **Wyszukiwanie Oparte na Umiejętnościach** - Przeszukuj historię projektu za pomocą umiejętności mem-search
- 🖥️ **Interfejs Przeglądarki Internetowej** - Strumień pamięci w czasie rzeczywistym pod adresem http://localhost:37777
- 💻 **Umiejętność Claude Desktop** - Przeszukuj pamięć z konwersacji Claude Desktop
- 🔒 **Kontrola Prywatności** - Użyj tagów `<private>`, aby wykluczyć wrażliwe treści z przechowywania
- ⚙️ **Konfiguracja Kontekstu** - Szczegółowa kontrola nad tym, jaki kontekst jest wstrzykiwany
- 🤖 **Automatyczne Działanie** - Nie wymaga ręcznej interwencji
- 🔗 **Cytowania** - Odniesienia do przeszłych obserwacji za pomocą identyfikatorów (dostęp przez http://localhost:37777/api/observation/{id} lub wyświetl wszystkie w przeglądarce internetowej pod adresem http://localhost:37777)
- 🧪 **Kanał Beta** - Wypróbuj eksperymentalne funkcje, takie jak Endless Mode, poprzez przełączanie wersji
---
## Dokumentacja
📚 **[Wyświetl Pełną Dokumentację](https://docs.claude-mem.ai/)** - Przeglądaj na oficjalnej stronie
### Pierwsze Kroki
- **[Przewodnik Instalacji](https://docs.claude-mem.ai/installation)** - Szybki start i zaawansowana instalacja
- **[Przewodnik Użytkowania](https://docs.claude-mem.ai/usage/getting-started)** - Jak Claude-Mem działa automatycznie
- **[Narzędzia Wyszukiwania](https://docs.claude-mem.ai/usage/search-tools)** - Przeszukuj historię projektu w języku naturalnym
- **[Funkcje Beta](https://docs.claude-mem.ai/beta-features)** - Wypróbuj eksperymentalne funkcje, takie jak Endless Mode
### Najlepsze Praktyki
- **[Inżynieria Kontekstu](https://docs.claude-mem.ai/context-engineering)** - Zasady optymalizacji kontekstu agenta AI
- **[Stopniowe Ujawnianie](https://docs.claude-mem.ai/progressive-disclosure)** - Filozofia strategii przygotowania kontekstu Claude-Mem
### Architektura
- **[Przegląd](https://docs.claude-mem.ai/architecture/overview)** - Komponenty systemu i przepływ danych
- **[Ewolucja Architektury](https://docs.claude-mem.ai/architecture-evolution)** - Droga od v3 do v5
- **[Architektura Hooków](https://docs.claude-mem.ai/hooks-architecture)** - Jak Claude-Mem wykorzystuje hooki cyklu życia
- **[Dokumentacja Hooków](https://docs.claude-mem.ai/architecture/hooks)** - 7 skryptów hooków wyjaśnionych
- **[Usługa Worker](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API i zarządzanie Bun
- **[Baza Danych](https://docs.claude-mem.ai/architecture/database)** - Schemat SQLite i wyszukiwanie FTS5
- **[Architektura Wyszukiwania](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrydowe wyszukiwanie z bazą wektorów Chroma
### Konfiguracja i Rozwój
- **[Konfiguracja](https://docs.claude-mem.ai/configuration)** - Zmienne środowiskowe i ustawienia
- **[Rozwój](https://docs.claude-mem.ai/development)** - Budowanie, testowanie, współpraca
- **[Rozwiązywanie Problemów](https://docs.claude-mem.ai/troubleshooting)** - Typowe problemy i rozwiązania
---
## Jak To Działa
**Główne Komponenty:**
1. **5 Hooków Cyklu Życia** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 skryptów hooków)
2. **Inteligentna Instalacja** - Buforowany sprawdzacz zależności (skrypt pre-hook, nie hook cyklu życia)
3. **Usługa Worker** - HTTP API na porcie 37777 z interfejsem przeglądarki internetowej i 10 punktami końcowymi wyszukiwania, zarządzana przez Bun
4. **Baza Danych SQLite** - Przechowuje sesje, obserwacje, podsumowania
5. **Umiejętność mem-search** - Zapytania w języku naturalnym ze stopniowym ujawnianiem
6. **Baza Wektorów Chroma** - Hybrydowe wyszukiwanie semantyczne + słowa kluczowe dla inteligentnego pobierania kontekstu
Zobacz [Przegląd Architektury](https://docs.claude-mem.ai/architecture/overview) dla szczegółów.
---
## Umiejętność mem-search
Claude-Mem zapewnia inteligentne wyszukiwanie poprzez umiejętność mem-search, która automatycznie aktywuje się, gdy pytasz o przeszłą pracę:
**Jak To Działa:**
- Po prostu pytaj naturalnie: *"Co robiliśmy w ostatniej sesji?"* lub *"Czy naprawiliśmy ten błąd wcześniej?"*
- Claude automatycznie wywołuje umiejętność mem-search, aby znaleźć odpowiedni kontekst
**Dostępne Operacje Wyszukiwania:**
1. **Search Observations** - Wyszukiwanie pełnotekstowe w obserwacjach
2. **Search Sessions** - Wyszukiwanie pełnotekstowe w podsumowaniach sesji
3. **Search Prompts** - Wyszukiwanie surowych żądań użytkownika
4. **By Concept** - Znajdź według tagów koncepcyjnych (discovery, problem-solution, pattern, itp.)
5. **By File** - Znajdź obserwacje odnoszące się do określonych plików
6. **By Type** - Znajdź według typu (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Pobierz ostatni kontekst sesji dla projektu
8. **Timeline** - Uzyskaj ujednoliconą oś czasu kontekstu wokół określonego punktu w czasie
9. **Timeline by Query** - Wyszukaj obserwacje i uzyskaj kontekst osi czasu wokół najlepszego dopasowania
10. **API Help** - Uzyskaj dokumentację API wyszukiwania
**Przykładowe Zapytania w Języku Naturalnym:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Zobacz [Przewodnik Narzędzi Wyszukiwania](https://docs.claude-mem.ai/usage/search-tools) dla szczegółowych przykładów.
---
## Funkcje Beta
Claude-Mem oferuje **kanał beta** z eksperymentalnymi funkcjami, takimi jak **Endless Mode** (biomimetyczna architektura pamięci dla rozszerzonych sesji). Przełączaj się między stabilnymi a beta wersjami z interfejsu przeglądarki internetowej pod adresem http://localhost:37777 → Settings.
Zobacz **[Dokumentacja Funkcji Beta](https://docs.claude-mem.ai/beta-features)** dla szczegółów dotyczących Endless Mode i sposobu wypróbowania.
---
## Wymagania Systemowe
- **Node.js**: 18.0.0 lub wyższy
- **Claude Code**: Najnowsza wersja z obsługą wtyczek
- **Bun**: Środowisko uruchomieniowe JavaScript i menedżer procesów (automatycznie instalowany, jeśli brakuje)
- **uv**: Menedżer pakietów Python do wyszukiwania wektorowego (automatycznie instalowany, jeśli brakuje)
- **SQLite 3**: Do trwałego przechowywania (dołączony)
---
## Konfiguracja
Ustawienia są zarządzane w `~/.claude-mem/settings.json` (automatycznie tworzone z domyślnymi wartościami przy pierwszym uruchomieniu). Skonfiguruj model AI, port workera, katalog danych, poziom logowania i ustawienia wstrzykiwania kontekstu.
Zobacz **[Przewodnik Konfiguracji](https://docs.claude-mem.ai/configuration)** dla wszystkich dostępnych ustawień i przykładów.
---
## Rozwój
Zobacz **[Przewodnik Rozwoju](https://docs.claude-mem.ai/development)** dla instrukcji budowania, testowania i przepływu pracy współpracy.
---
## Rozwiązywanie Problemów
Jeśli napotkasz problemy, opisz problem Claude, a umiejętność troubleshoot automatycznie zdiagnozuje i dostarczy poprawki.
Zobacz **[Przewodnik Rozwiązywania Problemów](https://docs.claude-mem.ai/troubleshooting)** dla typowych problemów i rozwiązań.
---
## Zgłoszenia Błędów
Twórz kompleksowe raporty błędów za pomocą automatycznego generatora:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Współpraca
Wkład jest mile widziany! Proszę:
1. Forkuj repozytorium
2. Utwórz gałąź funkcji
3. Dokonaj zmian z testami
4. Zaktualizuj dokumentację
5. Prześlij Pull Request
Zobacz [Przewodnik Rozwoju](https://docs.claude-mem.ai/development) dla przepływu pracy współpracy.
---
## Licencja
Ten projekt jest licencjonowany na podstawie **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Wszelkie prawa zastrzeżone.
Zobacz plik [LICENSE](LICENSE) dla pełnych szczegółów.
**Co To Oznacza:**
- Możesz używać, modyfikować i dystrybuować to oprogramowanie swobodnie
- Jeśli zmodyfikujesz i wdrożysz na serwerze sieciowym, musisz udostępnić swój kod źródłowy
- Dzieła pochodne muszą być również licencjonowane na podstawie AGPL-3.0
- Nie ma GWARANCJI dla tego oprogramowania
**Uwaga o Ragtime**: Katalog `ragtime/` jest licencjonowany osobno na podstawie **PolyForm Noncommercial License 1.0.0**. Zobacz [ragtime/LICENSE](ragtime/LICENSE) dla szczegółów.
---
## Wsparcie
- **Dokumentacja**: [docs/](docs/)
- **Problemy**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repozytorium**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Zbudowano za pomocą Claude Agent SDK** | **Zasilane przez Claude Code** | **Wykonane w TypeScript**

304
.agent/services/claude-mem/docs/i18n/README.pt-br.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Esta é uma tradução automatizada. Correções da comunidade são bem-vindas!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistema de compressão de memória persistente construído para <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#início-rápido">Início Rápido</a> •
<a href="#como-funciona">Como Funciona</a> •
<a href="#ferramentas-de-busca-mcp">Ferramentas de Busca</a> •
<a href="#documentação">Documentação</a> •
<a href="#configuração">Configuração</a> •
<a href="#solução-de-problemas">Solução de Problemas</a> •
<a href="#licença">Licença</a>
</p>
<p align="center">
Claude-Mem preserva o contexto perfeitamente entre sessões, capturando automaticamente observações de uso de ferramentas, gerando resumos semânticos e disponibilizando-os para sessões futuras. Isso permite que Claude mantenha a continuidade do conhecimento sobre projetos mesmo após o término ou reconexão de sessões.
</p>
---
## Início Rápido
Inicie uma nova sessão do Claude Code no terminal e digite os seguintes comandos:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Reinicie o Claude Code. O contexto de sessões anteriores aparecerá automaticamente em novas sessões.
**Principais Recursos:**
- 🧠 **Memória Persistente** - O contexto sobrevive entre sessões
- 📊 **Divulgação Progressiva** - Recuperação de memória em camadas com visibilidade de custo de tokens
- 🔍 **Busca Baseada em Skill** - Consulte seu histórico de projeto com a skill mem-search
- 🖥️ **Interface Web de Visualização** - Fluxo de memória em tempo real em http://localhost:37777
- 💻 **Skill para Claude Desktop** - Busque memória em conversas do Claude Desktop
- 🔒 **Controle de Privacidade** - Use tags `<private>` para excluir conteúdo sensível do armazenamento
- ⚙️ **Configuração de Contexto** - Controle refinado sobre qual contexto é injetado
- 🤖 **Operação Automática** - Nenhuma intervenção manual necessária
- 🔗 **Citações** - Referencie observações passadas com IDs (acesse via http://localhost:37777/api/observation/{id} ou visualize todas no visualizador web em http://localhost:37777)
- 🧪 **Canal Beta** - Experimente recursos experimentais como o Endless Mode através da troca de versões
---
## Documentação
📚 **[Ver Documentação Completa](https://docs.claude-mem.ai/)** - Navegar no site oficial
### Começando
- **[Guia de Instalação](https://docs.claude-mem.ai/installation)** - Início rápido e instalação avançada
- **[Guia de Uso](https://docs.claude-mem.ai/usage/getting-started)** - Como Claude-Mem funciona automaticamente
- **[Ferramentas de Busca](https://docs.claude-mem.ai/usage/search-tools)** - Consulte seu histórico de projeto com linguagem natural
- **[Recursos Beta](https://docs.claude-mem.ai/beta-features)** - Experimente recursos experimentais como o Endless Mode
### Melhores Práticas
- **[Engenharia de Contexto](https://docs.claude-mem.ai/context-engineering)** - Princípios de otimização de contexto para agentes de IA
- **[Divulgação Progressiva](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia por trás da estratégia de preparação de contexto do Claude-Mem
### Arquitetura
- **[Visão Geral](https://docs.claude-mem.ai/architecture/overview)** - Componentes do sistema e fluxo de dados
- **[Evolução da Arquitetura](https://docs.claude-mem.ai/architecture-evolution)** - A jornada da v3 à v5
- **[Arquitetura de Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Como Claude-Mem usa hooks de ciclo de vida
- **[Referência de Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 scripts de hook explicados
- **[Serviço Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP e gerenciamento do Bun
- **[Banco de Dados](https://docs.claude-mem.ai/architecture/database)** - Schema SQLite e busca FTS5
- **[Arquitetura de Busca](https://docs.claude-mem.ai/architecture/search-architecture)** - Busca híbrida com banco de dados vetorial Chroma
### Configuração e Desenvolvimento
- **[Configuração](https://docs.claude-mem.ai/configuration)** - Variáveis de ambiente e configurações
- **[Desenvolvimento](https://docs.claude-mem.ai/development)** - Build, testes e contribuição
- **[Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** - Problemas comuns e soluções
---
## Como Funciona
**Componentes Principais:**
1. **5 Hooks de Ciclo de Vida** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripts de hook)
2. **Instalação Inteligente** - Verificador de dependências em cache (script pré-hook, não um hook de ciclo de vida)
3. **Serviço Worker** - API HTTP na porta 37777 com interface de visualização web e 10 endpoints de busca, gerenciado pelo Bun
4. **Banco de Dados SQLite** - Armazena sessões, observações, resumos
5. **Skill mem-search** - Consultas em linguagem natural com divulgação progressiva
6. **Banco de Dados Vetorial Chroma** - Busca híbrida semântica + palavra-chave para recuperação inteligente de contexto
Veja [Visão Geral da Arquitetura](https://docs.claude-mem.ai/architecture/overview) para detalhes.
---
## Skill mem-search
Claude-Mem fornece busca inteligente através da skill mem-search que se auto-invoca quando você pergunta sobre trabalhos anteriores:
**Como Funciona:**
- Apenas pergunte naturalmente: *"O que fizemos na última sessão?"* ou *"Já corrigimos esse bug antes?"*
- Claude invoca automaticamente a skill mem-search para encontrar contexto relevante
**Operações de Busca Disponíveis:**
1. **Search Observations** - Busca de texto completo em observações
2. **Search Sessions** - Busca de texto completo em resumos de sessão
3. **Search Prompts** - Busca em solicitações brutas do usuário
4. **By Concept** - Encontre por tags de conceito (discovery, problem-solution, pattern, etc.)
5. **By File** - Encontre observações que referenciam arquivos específicos
6. **By Type** - Encontre por tipo (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Obtenha contexto de sessão recente para um projeto
8. **Timeline** - Obtenha linha do tempo unificada de contexto em torno de um ponto específico no tempo
9. **Timeline by Query** - Busque observações e obtenha contexto de linha do tempo em torno da melhor correspondência
10. **API Help** - Obtenha documentação da API de busca
**Exemplos de Consultas em Linguagem Natural:**
```
"Quais bugs corrigimos na última sessão?"
"Como implementamos a autenticação?"
"Quais mudanças foram feitas em worker-service.ts?"
"Mostre-me trabalhos recentes neste projeto"
"O que estava acontecendo quando adicionamos a interface de visualização?"
```
Veja [Guia de Ferramentas de Busca](https://docs.claude-mem.ai/usage/search-tools) para exemplos detalhados.
---
## Recursos Beta
Claude-Mem oferece um **canal beta** com recursos experimentais como **Endless Mode** (arquitetura de memória biomimética para sessões estendidas). Alterne entre versões estável e beta pela interface de visualização web em http://localhost:37777 → Settings.
Veja **[Documentação de Recursos Beta](https://docs.claude-mem.ai/beta-features)** para detalhes sobre o Endless Mode e como experimentá-lo.
---
## Requisitos do Sistema
- **Node.js**: 18.0.0 ou superior
- **Claude Code**: Versão mais recente com suporte a plugins
- **Bun**: Runtime JavaScript e gerenciador de processos (instalado automaticamente se ausente)
- **uv**: Gerenciador de pacotes Python para busca vetorial (instalado automaticamente se ausente)
- **SQLite 3**: Para armazenamento persistente (incluído)
---
## Configuração
As configurações são gerenciadas em `~/.claude-mem/settings.json` (criado automaticamente com valores padrão na primeira execução). Configure modelo de IA, porta do worker, diretório de dados, nível de log e configurações de injeção de contexto.
Veja o **[Guia de Configuração](https://docs.claude-mem.ai/configuration)** para todas as configurações disponíveis e exemplos.
---
## Desenvolvimento
Veja o **[Guia de Desenvolvimento](https://docs.claude-mem.ai/development)** para instruções de build, testes e fluxo de contribuição.
---
## Solução de Problemas
Se você estiver enfrentando problemas, descreva o problema para Claude e a skill troubleshoot diagnosticará automaticamente e fornecerá correções.
Veja o **[Guia de Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** para problemas comuns e soluções.
---
## Relatos de Bug
Crie relatos de bug abrangentes com o gerador automatizado:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contribuindo
Contribuições são bem-vindas! Por favor:
1. Faça um fork do repositório
2. Crie uma branch de feature
3. Faça suas alterações com testes
4. Atualize a documentação
5. Envie um Pull Request
Veja [Guia de Desenvolvimento](https://docs.claude-mem.ai/development) para o fluxo de contribuição.
---
## Licença
Este projeto está licenciado sob a **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Todos os direitos reservados.
Veja o arquivo [LICENSE](LICENSE) para detalhes completos.
**O Que Isso Significa:**
- Você pode usar, modificar e distribuir este software livremente
- Se você modificar e implantar em um servidor de rede, você deve disponibilizar seu código-fonte
- Trabalhos derivados também devem ser licenciados sob AGPL-3.0
- NÃO HÁ GARANTIA para este software
**Nota sobre Ragtime**: O diretório `ragtime/` é licenciado separadamente sob a **PolyForm Noncommercial License 1.0.0**. Veja [ragtime/LICENSE](ragtime/LICENSE) para detalhes.
---
## Suporte
- **Documentação**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositório**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Construído com Claude Agent SDK** | **Desenvolvido por Claude Code** | **Feito com TypeScript**

304
.agent/services/claude-mem/docs/i18n/README.ro.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Aceasta este o traducere automată. Corecțiile din partea comunității sunt binevenite!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistem persistent de compresie a memoriei construit pentru <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#start-rapid">Start Rapid</a> •
<a href="#cum-funcționează">Cum Funcționează</a> •
<a href="#instrumente-de-căutare-mcp">Instrumente de Căutare</a> •
<a href="#documentație">Documentație</a> •
<a href="#configurare">Configurare</a> •
<a href="#depanare">Depanare</a> •
<a href="#licență">Licență</a>
</p>
<p align="center">
Claude-Mem păstrează contextul fără întrerupere între sesiuni prin capturarea automată a observațiilor de utilizare a instrumentelor, generarea de rezumate semantice și punerea lor la dispoziție în sesiunile viitoare. Aceasta permite lui Claude să mențină continuitatea cunoștințelor despre proiecte chiar și după încheierea sau reconectarea sesiunilor.
</p>
---
## Start Rapid
Porniți o nouă sesiune Claude Code în terminal și introduceți următoarele comenzi:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Reporniți Claude Code. Contextul din sesiunile anterioare va apărea automat în sesiunile noi.
**Caracteristici Principale:**
- 🧠 **Memorie Persistentă** - Contextul supraviețuiește între sesiuni
- 📊 **Dezvăluire Progresivă** - Recuperare stratificată a memoriei cu vizibilitatea costurilor în tokeni
- 🔍 **Căutare Bazată pe Abilități** - Interogați istoricul proiectului cu abilitatea mem-search
- 🖥️ **Interfață Web Viewer** - Flux de memorie în timp real la http://localhost:37777
- 💻 **Abilitate Claude Desktop** - Căutați în memorie din conversațiile Claude Desktop
- 🔒 **Control al Confidențialității** - Utilizați etichete `<private>` pentru a exclude conținut sensibil de la stocare
- ⚙️ **Configurare Context** - Control fin asupra contextului care este injectat
- 🤖 **Operare Automată** - Nu necesită intervenție manuală
- 🔗 **Citări** - Referință la observații anterioare cu ID-uri (accesați prin http://localhost:37777/api/observation/{id} sau vizualizați toate în web viewer la http://localhost:37777)
- 🧪 **Canal Beta** - Încercați funcții experimentale precum Endless Mode prin comutarea versiunii
---
## Documentație
📚 **[Vizualizați Documentația Completă](https://docs.claude-mem.ai/)** - Răsfoiți pe site-ul oficial
### Introducere
- **[Ghid de Instalare](https://docs.claude-mem.ai/installation)** - Start rapid și instalare avansată
- **[Ghid de Utilizare](https://docs.claude-mem.ai/usage/getting-started)** - Cum funcționează Claude-Mem automat
- **[Instrumente de Căutare](https://docs.claude-mem.ai/usage/search-tools)** - Interogați istoricul proiectului cu limbaj natural
- **[Funcții Beta](https://docs.claude-mem.ai/beta-features)** - Încercați funcții experimentale precum Endless Mode
### Practici Recomandate
- **[Inginerie Context](https://docs.claude-mem.ai/context-engineering)** - Principii de optimizare a contextului pentru agenți AI
- **[Dezvăluire Progresivă](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia din spatele strategiei de pregătire a contextului Claude-Mem
### Arhitectură
- **[Prezentare Generală](https://docs.claude-mem.ai/architecture/overview)** - Componente de sistem și flux de date
- **[Evoluția Arhitecturii](https://docs.claude-mem.ai/architecture-evolution)** - Parcursul de la v3 la v5
- **[Arhitectura Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Cum folosește Claude-Mem hook-urile de ciclu de viață
- **[Referință Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 scripturi de hook explicate
- **[Serviciu Worker](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API și gestionare Bun
- **[Baza de Date](https://docs.claude-mem.ai/architecture/database)** - Schemă SQLite și căutare FTS5
- **[Arhitectura Căutării](https://docs.claude-mem.ai/architecture/search-architecture)** - Căutare hibridă cu baza de date vectorială Chroma
### Configurare și Dezvoltare
- **[Configurare](https://docs.claude-mem.ai/configuration)** - Variabile de mediu și setări
- **[Dezvoltare](https://docs.claude-mem.ai/development)** - Construire, testare, contribuție
- **[Depanare](https://docs.claude-mem.ai/troubleshooting)** - Probleme comune și soluții
---
## Cum Funcționează
**Componente Principale:**
1. **5 Hook-uri de Ciclu de Viață** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripturi de hook)
2. **Instalare Inteligentă** - Verificator de dependențe în cache (script pre-hook, nu un hook de ciclu de viață)
3. **Serviciu Worker** - HTTP API pe portul 37777 cu interfață web viewer și 10 endpoint-uri de căutare, gestionat de Bun
4. **Bază de Date SQLite** - Stochează sesiuni, observații, rezumate
5. **Abilitatea mem-search** - Interogări în limbaj natural cu dezvăluire progresivă
6. **Bază de Date Vectorială Chroma** - Căutare hibridă semantică + cuvinte cheie pentru recuperare inteligentă a contextului
Consultați [Prezentarea Generală a Arhitecturii](https://docs.claude-mem.ai/architecture/overview) pentru detalii.
---
## Abilitatea mem-search
Claude-Mem oferă căutare inteligentă prin abilitatea mem-search care se invocă automat când întrebați despre lucrul trecut:
**Cum Funcționează:**
- Întrebați natural: *"Ce am făcut în sesiunea trecută?"* sau *"Am rezolvat acest bug înainte?"*
- Claude invocă automat abilitatea mem-search pentru a găsi contextul relevant
**Operații de Căutare Disponibile:**
1. **Search Observations** - Căutare full-text în observații
2. **Search Sessions** - Căutare full-text în rezumatele sesiunilor
3. **Search Prompts** - Căutare în cererile brute ale utilizatorilor
4. **By Concept** - Găsire după etichete de concept (discovery, problem-solution, pattern, etc.)
5. **By File** - Găsire de observații care fac referire la fișiere specifice
6. **By Type** - Găsire după tip (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Obținere context recent al sesiunii pentru un proiect
8. **Timeline** - Obținere cronologie unificată a contextului în jurul unui punct specific în timp
9. **Timeline by Query** - Căutare observații și obținere context cronologic în jurul celei mai bune potriviri
10. **API Help** - Obținere documentație API de căutare
**Exemple de Interogări în Limbaj Natural:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Consultați [Ghidul Instrumentelor de Căutare](https://docs.claude-mem.ai/usage/search-tools) pentru exemple detaliate.
---
## Funcții Beta
Claude-Mem oferă un **canal beta** cu funcții experimentale precum **Endless Mode** (arhitectură de memorie biomimetică pentru sesiuni extinse). Comutați între versiunile stabile și beta din interfața web viewer la http://localhost:37777 → Settings.
Consultați **[Documentația Funcțiilor Beta](https://docs.claude-mem.ai/beta-features)** pentru detalii despre Endless Mode și cum să îl încercați.
---
## Cerințe de Sistem
- **Node.js**: 18.0.0 sau superior
- **Claude Code**: Versiunea cea mai recentă cu suport pentru plugin-uri
- **Bun**: Runtime JavaScript și manager de procese (instalat automat dacă lipsește)
- **uv**: Manager de pachete Python pentru căutare vectorială (instalat automat dacă lipsește)
- **SQLite 3**: Pentru stocare persistentă (inclus)
---
## Configurare
Setările sunt gestionate în `~/.claude-mem/settings.json` (creat automat cu valori implicite la prima rulare). Configurați modelul AI, portul worker, directorul de date, nivelul de log și setările de injectare a contextului.
Consultați **[Ghidul de Configurare](https://docs.claude-mem.ai/configuration)** pentru toate setările disponibile și exemple.
---
## Dezvoltare
Consultați **[Ghidul de Dezvoltare](https://docs.claude-mem.ai/development)** pentru instrucțiuni de construire, testare și flux de contribuție.
---
## Depanare
Dacă întâmpinați probleme, descrieți problema lui Claude și abilitatea troubleshoot va diagnostica automat și va furniza soluții.
Consultați **[Ghidul de Depanare](https://docs.claude-mem.ai/troubleshooting)** pentru probleme comune și soluții.
---
## Rapoarte de Bug-uri
Creați rapoarte comprehensive de bug-uri cu generatorul automat:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contribuție
Contribuțiile sunt binevenite! Vă rugăm:
1. Faceți fork la repository
2. Creați o ramură de funcție
3. Faceți modificările cu teste
4. Actualizați documentația
5. Trimiteți un Pull Request
Consultați [Ghidul de Dezvoltare](https://docs.claude-mem.ai/development) pentru fluxul de contribuție.
---
## Licență
Acest proiect este licențiat sub **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Toate drepturile rezervate.
Consultați fișierul [LICENSE](LICENSE) pentru detalii complete.
**Ce Înseamnă Asta:**
- Puteți folosi, modifica și distribui acest software liber
- Dacă modificați și implementați pe un server de rețea, trebuie să faceți disponibil codul sursă
- Lucrările derivate trebuie să fie licențiate și ele sub AGPL-3.0
- NU EXISTĂ NICIO GARANȚIE pentru acest software
**Notă despre Ragtime**: Directorul `ragtime/` este licențiat separat sub **PolyForm Noncommercial License 1.0.0**. Consultați [ragtime/LICENSE](ragtime/LICENSE) pentru detalii.
---
## Suport
- **Documentație**: [docs/](docs/)
- **Probleme**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Construit cu Claude Agent SDK** | **Alimentat de Claude Code** | **Realizat cu TypeScript**

304
.agent/services/claude-mem/docs/i18n/README.ru.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Это автоматический перевод. Приветствуются исправления от сообщества!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Система сжатия постоянной памяти, созданная для <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#быстрый-старт">Быстрый старт</a> •
<a href="#как-это-работает">Как это работает</a> •
<a href="#инструменты-поиска-mcp">Инструменты поиска</a> •
<a href="#документация">Документация</a> •
<a href="#конфигурация">Конфигурация</a> •
<a href="#устранение-неполадок">Устранение неполадок</a> •
<a href="#лицензия">Лицензия</a>
</p>
<p align="center">
Claude-Mem бесшовно сохраняет контекст между сеансами, автоматически фиксируя наблюдения за использованием инструментов, генерируя семантические сводки и делая их доступными для будущих сеансов. Это позволяет Claude поддерживать непрерывность знаний о проектах даже после завершения или переподключения сеансов.
</p>
---
## Быстрый старт
Запустите новый сеанс Claude Code в терминале и введите следующие команды:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Перезапустите Claude Code. Контекст из предыдущих сеансов будет автоматически появляться в новых сеансах.
**Ключевые возможности:**
- 🧠 **Постоянная память** - Контекст сохраняется между сеансами
- 📊 **Прогрессивное раскрытие** - Многоуровневое извлечение памяти с видимостью стоимости токенов
- 🔍 **Поиск на основе навыков** - Запросы к истории проекта с помощью навыка mem-search
- 🖥️ **Веб-интерфейс просмотра** - Поток памяти в реальном времени на http://localhost:37777
- 💻 **Навык для Claude Desktop** - Поиск в памяти из разговоров Claude Desktop
- 🔒 **Контроль конфиденциальности** - Используйте теги `<private>` для исключения конфиденциального контента из хранилища
- ⚙️ **Настройка контекста** - Детальный контроль того, какой контекст внедряется
- 🤖 **Автоматическая работа** - Не требуется ручное вмешательство
- 🔗 **Цитирование** - Ссылки на прошлые наблюдения с помощью ID (доступ через http://localhost:37777/api/observation/{id} или просмотр всех в веб-интерфейсе на http://localhost:37777)
- 🧪 **Бета-канал** - Попробуйте экспериментальные функции, такие как режим Endless, переключая версии
---
## Документация
📚 **[Просмотреть полную документацию](https://docs.claude-mem.ai/)** - Просмотр на официальном сайте
### Начало работы
- **[Руководство по установке](https://docs.claude-mem.ai/installation)** - Быстрый старт и продвинутая установка
- **[Руководство по использованию](https://docs.claude-mem.ai/usage/getting-started)** - Как Claude-Mem работает автоматически
- **[Инструменты поиска](https://docs.claude-mem.ai/usage/search-tools)** - Запросы к истории проекта на естественном языке
- **[Бета-функции](https://docs.claude-mem.ai/beta-features)** - Попробуйте экспериментальные функции, такие как режим Endless
### Лучшие практики
- **[Инженерия контекста](https://docs.claude-mem.ai/context-engineering)** - Принципы оптимизации контекста для AI-агентов
- **[Прогрессивное раскрытие](https://docs.claude-mem.ai/progressive-disclosure)** - Философия стратегии подготовки контекста в Claude-Mem
### Архитектура
- **[Обзор](https://docs.claude-mem.ai/architecture/overview)** - Компоненты системы и поток данных
- **[Эволюция архитектуры](https://docs.claude-mem.ai/architecture-evolution)** - Путь от v3 к v5
- **[Архитектура хуков](https://docs.claude-mem.ai/hooks-architecture)** - Как Claude-Mem использует хуки жизненного цикла
- **[Справочник по хукам](https://docs.claude-mem.ai/architecture/hooks)** - Объяснение 7 скриптов хуков
- **[Сервис Worker](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API и управление Bun
- **[База данных](https://docs.claude-mem.ai/architecture/database)** - Схема SQLite и поиск FTS5
- **[Архитектура поиска](https://docs.claude-mem.ai/architecture/search-architecture)** - Гибридный поиск с векторной базой данных Chroma
### Конфигурация и разработка
- **[Конфигурация](https://docs.claude-mem.ai/configuration)** - Переменные окружения и настройки
- **[Разработка](https://docs.claude-mem.ai/development)** - Сборка, тестирование, участие в разработке
- **[Устранение неполадок](https://docs.claude-mem.ai/troubleshooting)** - Распространенные проблемы и решения
---
## Как это работает
**Основные компоненты:**
1. **5 хуков жизненного цикла** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 скриптов хуков)
2. **Умная установка** - Проверка кешированных зависимостей (скрипт предварительного хука, не является хуком жизненного цикла)
3. **Сервис Worker** - HTTP API на порту 37777 с веб-интерфейсом просмотра и 10 конечными точками поиска, управляемый Bun
4. **База данных SQLite** - Хранит сеансы, наблюдения, сводки
5. **Навык mem-search** - Запросы на естественном языке с прогрессивным раскрытием
6. **Векторная база данных Chroma** - Гибридный семантический + ключевой поиск для интеллектуального извлечения контекста
Подробности см. в [Обзоре архитектуры](https://docs.claude-mem.ai/architecture/overview).
---
## Навык mem-search
Claude-Mem предоставляет интеллектуальный поиск через навык mem-search, который автоматически вызывается, когда вы спрашиваете о прошлой работе:
**Как это работает:**
- Просто спросите естественно: *"Что мы делали в прошлом сеансе?"* или *"Мы исправляли этот баг раньше?"*
- Claude автоматически вызывает навык mem-search для поиска релевантного контекста
**Доступные операции поиска:**
1. **Поиск наблюдений** - Полнотекстовый поиск по наблюдениям
2. **Поиск сеансов** - Полнотекстовый поиск по сводкам сеансов
3. **Поиск запросов** - Поиск исходных пользовательских запросов
4. **По концепции** - Поиск по тегам концепций (discovery, problem-solution, pattern и т.д.)
5. **По файлу** - Поиск наблюдений, ссылающихся на конкретные файлы
6. **По типу** - Поиск по типу (decision, bugfix, feature, refactor, discovery, change)
7. **Недавний контекст** - Получение недавнего контекста сеанса для проекта
8. **Хронология** - Получение единой хронологии контекста вокруг определенного момента времени
9. **Хронология по запросу** - Поиск наблюдений и получение контекста хронологии вокруг наилучшего совпадения
10. **Справка по API** - Получение документации по API поиска
**Примеры запросов на естественном языке:**
```
"Какие баги мы исправили в прошлом сеансе?"
"Как мы реализовали аутентификацию?"
"Какие изменения были внесены в worker-service.ts?"
"Покажи недавнюю работу над этим проектом"
"Что происходило, когда мы добавляли интерфейс просмотра?"
```
Подробные примеры см. в [Руководстве по инструментам поиска](https://docs.claude-mem.ai/usage/search-tools).
---
## Бета-функции
Claude-Mem предлагает **бета-канал** с экспериментальными функциями, такими как **режим Endless** (биомиметическая архитектура памяти для расширенных сеансов). Переключайтесь между стабильной и бета-версиями из веб-интерфейса на http://localhost:37777 → Settings.
Подробности о режиме Endless и способах его опробовать см. в **[Документации по бета-функциям](https://docs.claude-mem.ai/beta-features)**.
---
## Системные требования
- **Node.js**: 18.0.0 или выше
- **Claude Code**: Последняя версия с поддержкой плагинов
- **Bun**: Среда выполнения JavaScript и менеджер процессов (автоматически устанавливается при отсутствии)
- **uv**: Менеджер пакетов Python для векторного поиска (автоматически устанавливается при отсутствии)
- **SQLite 3**: Для постоянного хранения (встроенный)
---
## Конфигурация
Настройки управляются в `~/.claude-mem/settings.json` (автоматически создается с настройками по умолчанию при первом запуске). Настройте AI-модель, порт worker, директорию данных, уровень логирования и параметры внедрения контекста.
Все доступные настройки и примеры см. в **[Руководстве по конфигурации](https://docs.claude-mem.ai/configuration)**.
---
## Разработка
Инструкции по сборке, тестированию и процессу участия в разработке см. в **[Руководстве по разработке](https://docs.claude-mem.ai/development)**.
---
## Устранение неполадок
При возникновении проблем опишите проблему Claude, и навык устранения неполадок автоматически выполнит диагностику и предоставит исправления.
Распространенные проблемы и решения см. в **[Руководстве по устранению неполадок](https://docs.claude-mem.ai/troubleshooting)**.
---
## Отчеты об ошибках
Создавайте подробные отчеты об ошибках с помощью автоматического генератора:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Участие в разработке
Приветствуются вклады! Пожалуйста:
1. Форкните репозиторий
2. Создайте ветку для функции
3. Внесите изменения с тестами
4. Обновите документацию
5. Отправьте Pull Request
Процесс участия см. в [Руководстве по разработке](https://docs.claude-mem.ai/development).
---
## Лицензия
Этот проект лицензирован под **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Все права защищены.
Полные сведения см. в файле [LICENSE](LICENSE).
**Что это означает:**
- Вы можете свободно использовать, модифицировать и распространять это программное обеспечение
- Если вы модифицируете и развертываете на сетевом сервере, вы должны сделать свой исходный код доступным
- Производные работы также должны быть лицензированы под AGPL-3.0
- Для этого программного обеспечения НЕТ ГАРАНТИЙ
**Примечание о Ragtime**: Директория `ragtime/` лицензирована отдельно под **PolyForm Noncommercial License 1.0.0**. Подробности см. в [ragtime/LICENSE](ragtime/LICENSE).
---
## Поддержка
- **Документация**: [docs/](docs/)
- **Проблемы**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Репозиторий**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Автор**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Создано с помощью Claude Agent SDK** | **Работает на Claude Code** | **Сделано на TypeScript**

304
.agent/services/claude-mem/docs/i18n/README.sv.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Detta är en automatiserad översättning. Bidrag från gemenskapen är välkomna!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Persistent minneskomprimeringsystem byggt för <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#snabbstart">Snabbstart</a> •
<a href="#hur-det-fungerar">Hur det fungerar</a> •
<a href="#sökverktyg-mcp">Sökverktyg</a> •
<a href="#dokumentation">Dokumentation</a> •
<a href="#konfiguration">Konfiguration</a> •
<a href="#felsökning">Felsökning</a> •
<a href="#licens">Licens</a>
</p>
<p align="center">
Claude-Mem bevarar sömlöst kontext mellan sessioner genom att automatiskt fånga observationer av verktygsanvändning, generera semantiska sammanfattningar och göra dem tillgängliga för framtida sessioner. Detta gör det möjligt för Claude att upprätthålla kontinuitet i kunskap om projekt även efter att sessioner avslutas eller återansluter.
</p>
---
## Snabbstart
Starta en ny Claude Code-session i terminalen och ange följande kommandon:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Starta om Claude Code. Kontext från tidigare sessioner kommer automatiskt att visas i nya sessioner.
**Nyckelfunktioner:**
- 🧠 **Persistent minne** - Kontext överlever mellan sessioner
- 📊 **Progressiv visning** - Skiktad minneshämtning med synlighet för tokenkostnad
- 🔍 **Färdighetsbaserad sökning** - Sök i din projekthistorik med mem-search-färdigheten
- 🖥️ **Webbvy-gränssnitt** - Realtidsminnesström på http://localhost:37777
- 💻 **Claude Desktop-färdighet** - Sök i minnet från Claude Desktop-konversationer
- 🔒 **Integritetskontroll** - Använd `<private>`-taggar för att exkludera känsligt innehåll från lagring
- ⚙️ **Kontextkonfiguration** - Detaljerad kontroll över vilken kontext som injiceras
- 🤖 **Automatisk drift** - Ingen manuell hantering krävs
- 🔗 **Citeringar** - Referera till tidigare observationer med ID:n (tillgängliga via http://localhost:37777/api/observation/{id} eller visa alla i webbvyn på http://localhost:37777)
- 🧪 **Betakanal** - Testa experimentella funktioner som Endless Mode via versionsväxling
---
## Dokumentation
📚 **[Visa fullständig dokumentation](https://docs.claude-mem.ai/)** - Bläddra på den officiella webbplatsen
### Komma igång
- **[Installationsguide](https://docs.claude-mem.ai/installation)** - Snabbstart och avancerad installation
- **[Användarguide](https://docs.claude-mem.ai/usage/getting-started)** - Hur Claude-Mem fungerar automatiskt
- **[Sökverktyg](https://docs.claude-mem.ai/usage/search-tools)** - Sök i din projekthistorik med naturligt språk
- **[Betafunktioner](https://docs.claude-mem.ai/beta-features)** - Testa experimentella funktioner som Endless Mode
### Bästa praxis
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Optimeringsmetoder för AI-agentkontext
- **[Progressiv visning](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofin bakom Claude-Mems kontextpriming-strategi
### Arkitektur
- **[Översikt](https://docs.claude-mem.ai/architecture/overview)** - Systemkomponenter och dataflöde
- **[Arkitekturutveckling](https://docs.claude-mem.ai/architecture-evolution)** - Resan från v3 till v5
- **[Hooks-arkitektur](https://docs.claude-mem.ai/hooks-architecture)** - Hur Claude-Mem använder livscykelkrokar
- **[Hooks-referens](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook-skript förklarade
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API och Bun-hantering
- **[Databas](https://docs.claude-mem.ai/architecture/database)** - SQLite-schema och FTS5-sökning
- **[Sökarkitektur](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybridsökning med Chroma-vektordatabas
### Konfiguration och utveckling
- **[Konfiguration](https://docs.claude-mem.ai/configuration)** - Miljövariabler och inställningar
- **[Utveckling](https://docs.claude-mem.ai/development)** - Bygga, testa, bidra
- **[Felsökning](https://docs.claude-mem.ai/troubleshooting)** - Vanliga problem och lösningar
---
## Hur det fungerar
**Kärnkomponenter:**
1. **5 livscykelkrokar** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook-skript)
2. **Smart installation** - Cachad beroendekontrollant (pre-hook-skript, inte en livscykelkrok)
3. **Worker Service** - HTTP API på port 37777 med webbvy-gränssnitt och 10 sökändpunkter, hanterat av Bun
4. **SQLite-databas** - Lagrar sessioner, observationer, sammanfattningar
5. **mem-search-färdighet** - Naturligspråkssökningar med progressiv visning
6. **Chroma-vektordatabas** - Hybrid semantisk + nyckelordssökning för intelligent kontexthämtning
Se [Arkitekturöversikt](https://docs.claude-mem.ai/architecture/overview) för detaljer.
---
## mem-search-färdighet
Claude-Mem tillhandahåller intelligent sökning genom mem-search-färdigheten som automatiskt aktiveras när du frågar om tidigare arbete:
**Hur det fungerar:**
- Fråga bara naturligt: *"Vad gjorde vi förra sessionen?"* eller *"Fixade vi den här buggen tidigare?"*
- Claude aktiverar automatiskt mem-search-färdigheten för att hitta relevant kontext
**Tillgängliga sökoperationer:**
1. **Search Observations** - Fulltextsökning över observationer
2. **Search Sessions** - Fulltextsökning över sessionssammanfattningar
3. **Search Prompts** - Sök i råa användarförfrågningar
4. **By Concept** - Hitta efter koncepttaggar (discovery, problem-solution, pattern, etc.)
5. **By File** - Hitta observationer som refererar till specifika filer
6. **By Type** - Hitta efter typ (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Hämta senaste sessionskontext för ett projekt
8. **Timeline** - Få en enhetlig tidslinje av kontext kring en specifik tidpunkt
9. **Timeline by Query** - Sök efter observationer och få tidslinjekontext kring bästa matchning
10. **API Help** - Få API-dokumentation för sökning
**Exempel på naturligspråkssökningar:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Se [Sökverktygsguide](https://docs.claude-mem.ai/usage/search-tools) för detaljerade exempel.
---
## Betafunktioner
Claude-Mem erbjuder en **betakanal** med experimentella funktioner som **Endless Mode** (biomimetisk minnesarkitektur för utökade sessioner). Växla mellan stabila och betaversioner från webbvy-gränssnittet på http://localhost:37777 → Settings.
Se **[Dokumentation för betafunktioner](https://docs.claude-mem.ai/beta-features)** för detaljer om Endless Mode och hur du testar det.
---
## Systemkrav
- **Node.js**: 18.0.0 eller högre
- **Claude Code**: Senaste versionen med plugin-stöd
- **Bun**: JavaScript-runtime och processhanterare (installeras automatiskt om den saknas)
- **uv**: Python-pakethanterare för vektorsökning (installeras automatiskt om den saknas)
- **SQLite 3**: För persistent lagring (ingår)
---
## Konfiguration
Inställningar hanteras i `~/.claude-mem/settings.json` (skapas automatiskt med standardvärden vid första körning). Konfigurera AI-modell, worker-port, datakatalog, loggnivå och kontextinjektionsinställningar.
Se **[Konfigurationsguide](https://docs.claude-mem.ai/configuration)** för alla tillgängliga inställningar och exempel.
---
## Utveckling
Se **[Utvecklingsguide](https://docs.claude-mem.ai/development)** för bygginstruktioner, testning och bidragsarbetsflöde.
---
## Felsökning
Om du upplever problem, beskriv problemet för Claude och felsökningsfärdigheten kommer automatiskt att diagnostisera och tillhandahålla lösningar.
Se **[Felsökningsguide](https://docs.claude-mem.ai/troubleshooting)** för vanliga problem och lösningar.
---
## Buggrapporter
Skapa omfattande buggrapporter med den automatiserade generatorn:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Bidrag
Bidrag är välkomna! Vänligen:
1. Forka repositoryt
2. Skapa en feature-gren
3. Gör dina ändringar med tester
4. Uppdatera dokumentationen
5. Skicka in en Pull Request
Se [Utvecklingsguide](https://docs.claude-mem.ai/development) för bidragsarbetsflöde.
---
## Licens
Detta projekt är licensierat under **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Alla rättigheter förbehållna.
Se [LICENSE](LICENSE)-filen för fullständiga detaljer.
**Vad detta betyder:**
- Du kan använda, modifiera och distribuera denna programvara fritt
- Om du modifierar och distribuerar på en nätverksserver måste du göra din källkod tillgänglig
- Härledda verk måste också licensieras under AGPL-3.0
- Det finns INGEN GARANTI för denna programvara
**Notering om Ragtime**: Katalogen `ragtime/` är licensierad separat under **PolyForm Noncommercial License 1.0.0**. Se [ragtime/LICENSE](ragtime/LICENSE) för detaljer.
---
## Support
- **Dokumentation**: [docs/](docs/)
- **Problem**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Författare**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Byggd med Claude Agent SDK** | **Drivs av Claude Code** | **Skapad med TypeScript**

303
.agent/services/claude-mem/docs/i18n/README.th.md Normal file
View File

@@ -0,0 +1,303 @@
🌐 นี่คือการแปลอัตโนมัติ ยินดีต้อนรับการแก้ไขจากชุมชน!
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">ระบบการบีบอัดหน่วยความจำถาวรที่สร้างขึ้นสำหรับ <a href="https://claude.com/claude-code" target="_blank">Claude Code</a></h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#quick-start">เริ่มต้นอย่างรวดเร็ว</a> •
<a href="#how-it-works">วิธีการทำงาน</a> •
<a href="#mcp-search-tools">เครื่องมือค้นหา</a> •
<a href="#documentation">เอกสาร</a> •
<a href="#configuration">การกำหนดค่า</a> •
<a href="#troubleshooting">การแก้ไขปัญหา</a> •
<a href="#license">ใบอนุญาต</a>
</p>
<p align="center">
Claude-Mem รักษาบริบทข้ามเซสชันได้อย่างราบรื่นโดยการบันทึกผลการสังเกตจากการใช้เครื่องมือโดยอัตโนมัติ สร้างสรุปความหมาย และทำให้พร้อมใช้งานสำหรับเซสชันในอนาคต ทำให้ Claude สามารถรักษาความต่อเนื่องของความรู้เกี่ยวกับโปรเจกต์แม้หลังจากเซสชันสิ้นสุดหรือเชื่อมต่อใหม่
</p>
---
## เริ่มต้นอย่างรวดเร็ว
เริ่มเซสชัน Claude Code ใหม่ในเทอร์มินัลและป้อนคำสั่งต่อไปนี้:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
รีสตาร์ท Claude Code บริบทจากเซสชันก่อนหน้าจะปรากฏในเซสชันใหม่โดยอัตโนมัติ
**คุณสมบัติหลัก:**
- 🧠 **หน่วยความจำถาวร** - บริบทยังคงอยู่ข้ามเซสชัน
- 📊 **การเปิดเผยแบบก้าวหน้า** - การดึงหน่วยความจำแบบชั้นพร้อมการแสดงต้นทุนโทเค็น
- 🔍 **การค้นหาตามทักษะ** - สืบค้นประวัติโปรเจกต์ของคุณด้วยทักษะ mem-search
- 🖥️ **Web Viewer UI** - สตรีมหน่วยความจำแบบเรียลไทม์ที่ http://localhost:37777
- 💻 **Claude Desktop Skill** - ค้นหาหน่วยความจำจากการสนทนา Claude Desktop
- 🔒 **การควบคุมความเป็นส่วนตัว** - ใช้แท็ก `<private>` เพื่อยกเว้นเนื้อหาที่ละเอียดอ่อนจากการจัดเก็บ
- ⚙️ **การกำหนดค่าบริบท** - ควบคุมบริบทที่ถูกฉีดเข้ามาได้อย่างละเอียด
- 🤖 **การทำงานอัตโนมัติ** - ไม่ต้องแทรกแซงด้วยตนเอง
- 🔗 **การอ้างอิง** - อ้างอิงการสังเกตในอดีตด้วย ID (เข้าถึงผ่าน http://localhost:37777/api/observation/{id} หรือดูทั้งหมดใน web viewer ที่ http://localhost:37777)
- 🧪 **Beta Channel** - ลองคุณสมบัติทดลองเช่น Endless Mode ผ่านการสลับเวอร์ชัน
---
## เอกสาร
📚 **[ดูเอกสารฉบับเต็ม](https://docs.claude-mem.ai/)** - เรียกดูบนเว็บไซต์อย่างเป็นทางการ
### เริ่มต้นใช้งาน
- **[คู่มือการติดตั้ง](https://docs.claude-mem.ai/installation)** - เริ่มต้นอย่างรวดเร็วและการติดตั้งขั้นสูง
- **[คู่มือการใช้งาน](https://docs.claude-mem.ai/usage/getting-started)** - วิธีที่ Claude-Mem ทำงานโดยอัตโนมัติ
- **[เครื่องมือค้นหา](https://docs.claude-mem.ai/usage/search-tools)** - สืบค้นประวัติโปรเจกต์ของคุณด้วยภาษาธรรมชาติ
- **[คุณสมบัติ Beta](https://docs.claude-mem.ai/beta-features)** - ลองคุณสมบัติทดลองเช่น Endless Mode
### แนวปฏิบัติที่ดี
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - หลักการปรับบริบทสำหรับเอเจนต์ AI
- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - ปรัชญาเบื้องหลังกลยุทธ์การเตรียมบริบทของ Claude-Mem
### สถาปัตยกรรม
- **[ภาพรวม](https://docs.claude-mem.ai/architecture/overview)** - ส่วนประกอบของระบบและการไหลของข้อมูล
- **[วิวัฒนาการของสถาปัตยกรรม](https://docs.claude-mem.ai/architecture-evolution)** - การเดินทางจาก v3 สู่ v5
- **[สถาปัตยกรรม Hooks](https://docs.claude-mem.ai/hooks-architecture)** - วิธีที่ Claude-Mem ใช้ lifecycle hooks
- **[การอ้างอิง Hooks](https://docs.claude-mem.ai/architecture/hooks)** - อธิบาย hook scripts ทั้ง 7 ตัว
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API และการจัดการ Bun
- **[ฐานข้อมูล](https://docs.claude-mem.ai/architecture/database)** - SQLite schema และการค้นหา FTS5
- **[สถาปัตยกรรมการค้นหา](https://docs.claude-mem.ai/architecture/search-architecture)** - การค้นหาแบบไฮบริดด้วยฐานข้อมูลเวกเตอร์ Chroma
### การกำหนดค่าและการพัฒนา
- **[การกำหนดค่า](https://docs.claude-mem.ai/configuration)** - ตัวแปรสภาพแวดล้อมและการตั้งค่า
- **[การพัฒนา](https://docs.claude-mem.ai/development)** - การสร้าง การทดสอบ การมีส่วนร่วม
- **[การแก้ไขปัญหา](https://docs.claude-mem.ai/troubleshooting)** - ปัญหาและการแก้ไขทั่วไป
---
## วิธีการทำงาน
**ส่วนประกอบหลัก:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. **Smart Install** - ตัวตรวจสอบการพึ่งพาที่ถูกแคช (pre-hook script, ไม่ใช่ lifecycle hook)
3. **Worker Service** - HTTP API บนพอร์ต 37777 พร้อม web viewer UI และ 10 search endpoints, จัดการโดย Bun
4. **SQLite Database** - จัดเก็บเซสชัน การสังเกต สรุป
5. **mem-search Skill** - คิวรีภาษาธรรมชาติพร้อมการเปิดเผยแบบก้าวหน้า
6. **Chroma Vector Database** - การค้นหาแบบไฮบริดทางความหมาย + คีย์เวิร์ดสำหรับการดึงบริบทอัจฉริยะ
ดู [ภาพรวมสถาปัตยกรรม](https://docs.claude-mem.ai/architecture/overview) สำหรับรายละเอียด
---
## ทักษะ mem-search
Claude-Mem ให้บริการการค้นหาอัจฉริยะผ่านทักษะ mem-search ที่เรียกใช้อัตโนมัติเมื่อคุณถามเกี่ยวกับงานที่ผ่านมา:
**วิธีการทำงาน:**
- เพียงถามตามธรรมชาติ: *"เราทำอะไรในเซสชันที่แล้ว?"* หรือ *"เราแก้บั๊กนี้ไปแล้วหรือยัง?"*
- Claude เรียกใช้ทักษะ mem-search โดยอัตโนมัติเพื่อค้นหาบริบทที่เกี่ยวข้อง
**การดำเนินการค้นหาที่มี:**
1. **Search Observations** - การค้นหาข้อความเต็มข้ามการสังเกต
2. **Search Sessions** - การค้นหาข้อความเต็มข้ามสรุปเซสชัน
3. **Search Prompts** - ค้นหาคำขอผู้ใช้แบบดิบ
4. **By Concept** - ค้นหาตามแท็กแนวคิด (discovery, problem-solution, pattern, ฯลฯ)
5. **By File** - ค้นหาการสังเกตที่อ้างอิงไฟล์เฉพาะ
6. **By Type** - ค้นหาตามประเภท (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - รับบริบทเซสชันล่าสุดสำหรับโปรเจกต์
8. **Timeline** - รับไทม์ไลน์รวมของบริบทรอบจุดเวลาเฉพาะ
9. **Timeline by Query** - ค้นหาการสังเกตและรับบริบทไทม์ไลน์รอบการจับคู่ที่ดีที่สุด
10. **API Help** - รับเอกสาร search API
**ตัวอย่างคิวรีภาษาธรรมชาติ:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
ดู [คู่มือเครื่องมือค้นหา](https://docs.claude-mem.ai/usage/search-tools) สำหรับตัวอย่างโดยละเอียด
---
## คุณสมบัติ Beta
Claude-Mem นำเสนอ **beta channel** พร้อมคุณสมบัติทดลองเช่น **Endless Mode** (สถาปัตยกรรมหน่วยความจำแบบชีวมิติสำหรับเซสชันที่ขยายออกไป) สลับระหว่างเวอร์ชันเสถียรและเบต้าจาก web viewer UI ที่ http://localhost:37777 → Settings
ดู **[เอกสารคุณสมบัติ Beta](https://docs.claude-mem.ai/beta-features)** สำหรับรายละเอียดเกี่ยวกับ Endless Mode และวิธีการลอง
---
## ความต้องการของระบบ
- **Node.js**: 18.0.0 หรือสูงกว่า
- **Claude Code**: เวอร์ชันล่าสุดพร้อมการสนับสนุนปลั๊กอิน
- **Bun**: JavaScript runtime และตัวจัดการกระบวนการ (ติดตั้งอัตโนมัติหากไม่มี)
- **uv**: ตัวจัดการแพ็คเกจ Python สำหรับการค้นหาเวกเตอร์ (ติดตั้งอัตโนมัติหากไม่มี)
- **SQLite 3**: สำหรับการจัดเก็บถาวร (รวมอยู่)
---
## การกำหนดค่า
การตั้งค่าจะถูกจัดการใน `~/.claude-mem/settings.json` (สร้างอัตโนมัติพร้อมค่าเริ่มต้นในการรันครั้งแรก) กำหนดค่าโมเดล AI พอร์ต worker ไดเรกทอรีข้อมูล ระดับ log และการตั้งค่าการฉีดบริบท
ดู **[คู่มือการกำหนดค่า](https://docs.claude-mem.ai/configuration)** สำหรับการตั้งค่าทั้งหมดที่มีและตัวอย่าง
---
## การพัฒนา
ดู **[คู่มือการพัฒนา](https://docs.claude-mem.ai/development)** สำหรับคำแนะนำการสร้าง การทดสอบ และขั้นตอนการมีส่วนร่วม
---
## การแก้ไขปัญหา
หากพบปัญหา อธิบายปัญหาให้ Claude ฟังและทักษะ troubleshoot จะวินิจฉัยและให้การแก้ไขโดยอัตโนมัติ
ดู **[คู่มือการแก้ไขปัญหา](https://docs.claude-mem.ai/troubleshooting)** สำหรับปัญหาและการแก้ไขทั่วไป
---
## รายงานบั๊ก
สร้างรายงานบั๊กที่ครอบคลุมด้วยตัวสร้างอัตโนมัติ:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## การมีส่วนร่วม
ยินดีรับการมีส่วนร่วม! กรุณา:
1. Fork repository
2. สร้าง feature branch
3. ทำการเปลี่ยนแปลงพร้อมการทดสอบ
4. อัปเดตเอกสาร
5. ส่ง Pull Request
ดู [คู่มือการพัฒนา](https://docs.claude-mem.ai/development) สำหรับขั้นตอนการมีส่วนร่วม
---
## ใบอนุญาต
โปรเจกต์นี้ได้รับอนุญาตภายใต้ **GNU Affero General Public License v3.0** (AGPL-3.0)
Copyright (C) 2025 Alex Newman (@thedotmack) สงวนลิขสิทธิ์ทั้งหมด
ดูไฟล์ [LICENSE](LICENSE) สำหรับรายละเอียดทั้งหมด
**ความหมาย:**
- คุณสามารถใช้ ดัดแปลง และแจกจ่ายซอฟต์แวร์นี้ได้อย่างอิสระ
- หากคุณดัดแปลงและปรับใช้บนเซิร์ฟเวอร์เครือข่าย คุณต้องทำให้ซอร์สโค้ดของคุณพร้อมใช้งาน
- งานที่เป็นอนุพันธ์ต้องได้รับอนุญาตภายใต้ AGPL-3.0 ด้วย
- ไม่มีการรับประกันสำหรับซอฟต์แวร์นี้
**หมายเหตุเกี่ยวกับ Ragtime**: ไดเรกทอรี `ragtime/` ได้รับอนุญาตแยกต่างหากภายใต้ **PolyForm Noncommercial License 1.0.0** ดู [ragtime/LICENSE](ragtime/LICENSE) สำหรับรายละเอียด
---
## การสนับสนุน
- **เอกสาร**: [docs/](docs/)
- **ปัญหา**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **ผู้เขียน**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**สร้างด้วย Claude Agent SDK** | **ขับเคลื่อนโดย Claude Code** | **สร้างด้วย TypeScript**

328
.agent/services/claude-mem/docs/i18n/README.tl.md Normal file
View File

@@ -0,0 +1,328 @@
🌐 Ito ay isang awtomatikong pagsasalin. Malugod na tinatanggap ang mga pagwawasto mula sa komunidad!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a> •
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.tl.md">🇵🇭 Tagalog</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistema ng kompresyon ng persistent memory na ginawa para sa <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#mabilis-na-pagsisimula">Mabilis na Pagsisimula</a> •
<a href="#paano-ito-gumagana">Paano Ito Gumagana</a> •
<a href="#mga-search-tool-ng-mcp">Mga Search Tool</a> •
<a href="#dokumentasyon">Dokumentasyon</a> •
<a href="#konpigurasyon">Konpigurasyon</a> •
<a href="#pag-troubleshoot">Pag-troubleshoot</a> •
<a href="#lisensya">Lisensya</a>
</p>
<p align="center">
Pinapanatili ng Claude-Mem ang konteksto sa pagitan ng mga session sa pamamagitan ng awtomatikong pagkuha ng mga obserbasyon sa paggamit ng mga tool, pagbuo ng mga semantikong buod, at paggawa nitong available sa mga susunod na session. Dahil dito, napapanatili ni Claude ang tuloy-tuloy na kaalaman tungkol sa mga proyekto kahit matapos o muling kumonekta ang mga session.
</p>
---
## Mabilis na Pagsisimula
Magsimula ng bagong Claude Code session sa terminal at ilagay ang mga sumusunod na command:
```
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```
I-restart ang Claude Code. Awtomatikong lalabas sa mga bagong session ang konteksto mula sa mga nakaraang session.
**Mga Pangunahing Tampok:**
- 🧠 **Persistent Memory** - Nananatili ang konteksto sa pagitan ng mga session
- 📊 **Progressive Disclosure** - Layered na pagkuha ng memory na may visibility ng token cost
- 🔍 **Skill-Based Search** - I-query ang history ng proyekto gamit ang mem-search skill
- 🖥️ **Web Viewer UI** - Real-time memory stream sa http://localhost:37777
- 💻 **Claude Desktop Skill** - Maghanap sa memory mula sa Claude Desktop conversations
- 🔒 **Privacy Control** - Gamitin ang `<private>` tags para hindi ma-store ang sensitibong nilalaman
- ⚙️ **Context Configuration** - Mas pinong kontrol kung anong konteksto ang ini-inject
- 🤖 **Automatic Operation** - Walang kailangang manual na intervention
- 🔗 **Citations** - I-refer ang mga lumang obserbasyon gamit ang IDs (i-access sa http://localhost:37777/api/observation/{id} o tingnan lahat sa web viewer sa http://localhost:37777)
- 🧪 **Beta Channel** - Subukan ang mga experimental feature tulad ng Endless Mode sa pamamagitan ng version switching
---
## Dokumentasyon
📚 **[Tingnan ang Buong Dokumentasyon](https://docs.claude-mem.ai/)** - I-browse sa opisyal na website
### Pagsisimula
- **[Gabay sa Pag-install](https://docs.claude-mem.ai/installation)** - Mabilis na pagsisimula at advanced installation
- **[Gabay sa Paggamit](https://docs.claude-mem.ai/usage/getting-started)** - Paano awtomatikong gumagana ang Claude-Mem
- **[Mga Search Tool](https://docs.claude-mem.ai/usage/search-tools)** - I-query ang history ng proyekto gamit ang natural language
- **[Mga Beta Feature](https://docs.claude-mem.ai/beta-features)** - Subukan ang mga experimental feature tulad ng Endless Mode
### Best Practices
- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Mga prinsipyo ng context optimization para sa AI agents
- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Pilosopiya sa likod ng context priming strategy ng Claude-Mem
### Arkitektura
- **[Overview](https://docs.claude-mem.ai/architecture/overview)** - Mga bahagi ng sistema at daloy ng data
- **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - Ang paglalakbay mula v3 hanggang v5
- **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - Paano gumagamit ang Claude-Mem ng lifecycle hooks
- **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts, ipinaliwanag
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API at Bun management
- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema at FTS5 search
- **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search gamit ang Chroma vector database
### Konpigurasyon at Pagbuo
- **[Konpigurasyon](https://docs.claude-mem.ai/configuration)** - Environment variables at settings
- **[Pagbuo](https://docs.claude-mem.ai/development)** - Build, test, at contribution workflow
- **[Pag-troubleshoot](https://docs.claude-mem.ai/troubleshooting)** - Karaniwang isyu at solusyon
---
## Paano Ito Gumagana
**Mga Pangunahing Bahagi:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. **Smart Install** - Cached dependency checker (pre-hook script, hindi lifecycle hook)
3. **Worker Service** - HTTP API sa port 37777 na may web viewer UI at 10 search endpoints, pinamamahalaan ng Bun
4. **SQLite Database** - Nag-iimbak ng sessions, observations, summaries
5. **mem-search Skill** - Natural language queries na may progressive disclosure
6. **Chroma Vector Database** - Hybrid semantic + keyword search para sa matalinong pagkuha ng konteksto
Tingnan ang [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) para sa detalye.
---
## Mga Search Tool ng MCP
Nagbibigay ang Claude-Mem ng intelligent memory search sa pamamagitan ng **5 MCP tools** na sumusunod sa token-efficient na **3-layer workflow pattern**:
**Ang 3-Layer Workflow:**
1. **`search`** - Kumuha ng compact index na may IDs (~50-100 tokens/result)
2. **`timeline`** - Kumuha ng chronological context sa paligid ng mga interesting na result
3. **`get_observations`** - Kunin ang full details PARA LANG sa na-filter na IDs (~500-1,000 tokens/result)
**Paano Ito Gumagana:**
- Gumagamit si Claude ng MCP tools para maghanap sa iyong memory
- Magsimula sa `search` para makakuha ng index ng results
- Gamitin ang `timeline` para makita ang nangyari sa paligid ng mga partikular na observation
- Gamitin ang `get_observations` para kunin ang full details ng mga relevant na IDs
- Gamitin ang `save_memory` para manual na mag-store ng importanteng impormasyon
- **~10x tipid sa tokens** dahil nagfi-filter muna bago kunin ang full details
**Available na MCP Tools:**
1. **`search`** - Hanapin ang memory index gamit ang full-text queries, may filters (type/date/project)
2. **`timeline`** - Kumuha ng chronological context sa paligid ng isang observation o query
3. **`get_observations`** - Kumuha ng full observation details gamit ang IDs (laging i-batch ang maraming IDs)
4. **`save_memory`** - Manual na mag-save ng memory/observation para sa semantic search
5. **`__IMPORTANT`** - Workflow documentation (laging visible kay Claude)
**Halimbawa ng Paggamit:**
```typescript
// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
// Step 3: Fetch full details
get_observations(ids=[123, 456])
// Save important information manually
save_memory(text="API requires auth header X-API-Key", title="API Auth")
```
Tingnan ang [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) para sa mas detalyadong mga halimbawa.
---
## Mga Beta Feature
May **beta channel** ang Claude-Mem na may mga experimental feature gaya ng **Endless Mode** (biomimetic memory architecture para sa mas mahahabang session). Magpalit sa pagitan ng stable at beta versions sa web viewer UI sa http://localhost:37777 → Settings.
Tingnan ang **[Dokumentasyon ng Mga Beta Feature](https://docs.claude-mem.ai/beta-features)** para sa detalye ng Endless Mode at kung paano ito subukan.
---
## Mga Pangangailangan ng Sistema
- **Node.js**: 18.0.0 o mas mataas
- **Claude Code**: Pinakabagong bersyon na may plugin support
- **Bun**: JavaScript runtime at process manager (auto-installed kung wala)
- **uv**: Python package manager para sa vector search (auto-installed kung wala)
- **SQLite 3**: Para sa persistent storage (kasama)
---
### Mga Tala sa Windows Setup
Kung makakita ka ng error gaya ng:
```powershell
npm : The term 'npm' is not recognized as the name of a cmdlet
```
Siguraduhing naka-install ang Node.js at npm at nakadagdag sa PATH. I-download ang pinakabagong Node.js installer mula sa https://nodejs.org at i-restart ang terminal matapos mag-install.
---
## Konpigurasyon
Pinamamahalaan ang settings sa `~/.claude-mem/settings.json` (auto-created na may defaults sa unang run). I-configure ang AI model, worker port, data directory, log level, at context injection settings.
Tingnan ang **[Gabay sa Konpigurasyon](https://docs.claude-mem.ai/configuration)** para sa lahat ng available na settings at mga halimbawa.
---
## Pagbuo
Tingnan ang **[Gabay nang pagbuo](https://docs.claude-mem.ai/development)** para sa pag build instructions, testing, at contribution workflow.
---
## Pag-troubleshoot
Kung may issue, ilarawan ang problema kay Claude at awtomatikong magdi-diagnose at magbibigay ng mga ayos ang troubleshoot skill.
Tingnan ang **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** para sa mga karaniwang isyu at solusyon.
---
## Bug Reports
Gumawa ng kumpletong bug reports gamit ang automated generator:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Pag-aambag
Malugod na tinatanggap ang mga kontribusyon! Pakisunod:
1. I-fork ang repository
2. Gumawa ng feature branch
3. Gawin ang mga pagbabago kasama ang tests
4. I-update ang dokumentasyon
5. Mag-submit ng Pull Request
Tingnan ang [Gabay nang pagbuo](https://docs.claude-mem.ai/development) para sa contribution workflow.
---
## Lisensya
Ang proyektong ito ay licensed sa ilalim ng **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
Tingnan ang [LICENSE](LICENSE) file para sa buong detalye.
**Ano ang ibig sabihin nito:**
- Maaari mong gamitin, baguhin, at ipamahagi ang software na ito nang libre
- Kung babaguhin mo at i-deploy sa isang network server, kailangan mong gawing available ang iyong source code
- Dapat ding naka-license sa AGPL-3.0 ang mga derivative works
- WALANG WARRANTY para sa software na ito
**Tala tungkol sa Ragtime**: Ang `ragtime/` directory ay may hiwalay na lisensya sa ilalim ng **PolyForm Noncommercial License 1.0.0**. Tingnan ang [ragtime/LICENSE](ragtime/LICENSE) para sa detalye.
---
## Suporta
- **Dokumentasyon**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**

303
.agent/services/claude-mem/docs/i18n/README.tr.md Normal file
View File

@@ -0,0 +1,303 @@
🌐 Bu otomatik bir çevirisidir. Topluluk düzeltmeleri memnuniyetle karşılanır!
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center"><a href="https://claude.com/claude-code" target="_blank">Claude Code</a> için geliştirilmiş kalıcı bellek sıkıştırma sistemi.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#hızlı-başlangıç">Hızlı Başlangıç</a> •
<a href="#nasıl-çalışır">Nasıl Çalışır</a> •
<a href="#mcp-arama-araçları">Arama Araçları</a> •
<a href="#dokümantasyon">Dokümantasyon</a> •
<a href="#yapılandırma">Yapılandırma</a> •
<a href="#sorun-giderme">Sorun Giderme</a> •
<a href="#lisans">Lisans</a>
</p>
<p align="center">
Claude-Mem, araç kullanım gözlemlerini otomatik olarak yakalayarak, anlamsal özetler oluşturarak ve bunları gelecekteki oturumlarda kullanılabilir hale getirerek bağlamı oturumlar arası sorunsuzca korur. Bu, Claude'un oturumlar sona erse veya yeniden bağlansa bile projeler hakkındaki bilgi sürekliliğini korumasını sağlar.
</p>
---
## Hızlı Başlangıç
Terminal üzerinden yeni bir Claude Code oturumu başlatın ve aşağıdaki komutları girin:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Claude Code'u yeniden başlatın. Önceki oturumlardaki bağlam otomatik olarak yeni oturumlarda görünecektir.
**Temel Özellikler:**
- 🧠 **Kalıcı Bellek** - Bağlam oturumlar arası hayatta kalır
- 📊 **Aşamalı Açıklama** - Token maliyeti görünürlüğü ile katmanlı bellek erişimi
- 🔍 **Beceri Tabanlı Arama** - mem-search becerisi ile proje geçmişinizi sorgulayın
- 🖥️ **Web Görüntüleyici Arayüzü** - http://localhost:37777 adresinde gerçek zamanlı bellek akışı
- 💻 **Claude Desktop Becerisi** - Claude Desktop konuşmalarından bellek araması yapın
- 🔒 **Gizlilik Kontrolü** - Hassas içeriği depolamadan hariç tutmak için `<private>` etiketlerini kullanın
- ⚙️ **Bağlam Yapılandırması** - Hangi bağlamın enjekte edileceği üzerinde detaylı kontrol
- 🤖 **Otomatik Çalışma** - Manuel müdahale gerektirmez
- 🔗 **Alıntılar** - ID'lerle geçmiş gözlemlere referans verin (http://localhost:37777/api/observation/{id} üzerinden erişin veya http://localhost:37777 adresindeki web görüntüleyicide tümünü görüntüleyin)
- 🧪 **Beta Kanalı** - Sürüm değiştirme yoluyla Endless Mode gibi deneysel özellikleri deneyin
---
## Dokümantasyon
📚 **[Tam Dokümantasyonu Görüntüle](https://docs.claude-mem.ai/)** - Resmi web sitesinde göz atın
### Başlarken
- **[Kurulum Kılavuzu](https://docs.claude-mem.ai/installation)** - Hızlı başlangıç ve gelişmiş kurulum
- **[Kullanım Kılavuzu](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem otomatik olarak nasıl çalışır
- **[Arama Araçları](https://docs.claude-mem.ai/usage/search-tools)** - Doğal dil ile proje geçmişinizi sorgulayın
- **[Beta Özellikleri](https://docs.claude-mem.ai/beta-features)** - Endless Mode gibi deneysel özellikleri deneyin
### En İyi Uygulamalar
- **[Bağlam Mühendisliği](https://docs.claude-mem.ai/context-engineering)** - AI ajan bağlam optimizasyon ilkeleri
- **[Aşamalı Açıklama](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem'in bağlam hazırlama stratejisinin ardındaki felsefe
### Mimari
- **[Genel Bakış](https://docs.claude-mem.ai/architecture/overview)** - Sistem bileşenleri ve veri akışı
- **[Mimari Evrimi](https://docs.claude-mem.ai/architecture-evolution)** - v3'ten v5'e yolculuk
- **[Hooks Mimarisi](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem yaşam döngüsü hook'larını nasıl kullanır
- **[Hooks Referansı](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook betiği açıklandı
- **[Worker Servisi](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API ve Bun yönetimi
- **[Veritabanı](https://docs.claude-mem.ai/architecture/database)** - SQLite şeması ve FTS5 arama
- **[Arama Mimarisi](https://docs.claude-mem.ai/architecture/search-architecture)** - Chroma vektör veritabanı ile hibrit arama
### Yapılandırma ve Geliştirme
- **[Yapılandırma](https://docs.claude-mem.ai/configuration)** - Ortam değişkenleri ve ayarlar
- **[Geliştirme](https://docs.claude-mem.ai/development)** - Derleme, test etme, katkıda bulunma
- **[Sorun Giderme](https://docs.claude-mem.ai/troubleshooting)** - Yaygın sorunlar ve çözümler
---
## Nasıl Çalışır
**Temel Bileşenler:**
1. **5 Yaşam Döngüsü Hook'u** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook betiği)
2. **Akıllı Kurulum** - Önbelleğe alınmış bağımlılık kontrolcüsü (ön-hook betiği, yaşam döngüsü hook'u değil)
3. **Worker Servisi** - Web görüntüleyici arayüzü ve 10 arama uç noktası ile 37777 portunda HTTP API, Bun tarafından yönetilir
4. **SQLite Veritabanı** - Oturumları, gözlemleri, özetleri saklar
5. **mem-search Becerisi** - Aşamalı açıklama ile doğal dil sorguları
6. **Chroma Vektör Veritabanı** - Akıllı bağlam erişimi için hibrit anlamsal + anahtar kelime arama
Detaylar için [Mimari Genel Bakış](https://docs.claude-mem.ai/architecture/overview) bölümüne bakın.
---
## mem-search Becerisi
Claude-Mem, geçmiş çalışmalarınız hakkında sorduğunuzda otomatik olarak devreye giren mem-search becerisi aracılığıyla akıllı arama sağlar:
**Nasıl Çalışır:**
- Sadece doğal bir şekilde sorun: *"Geçen oturumda ne yaptık?"* veya *"Bu hatayı daha önce düzelttik mi?"*
- Claude, ilgili bağlamı bulmak için otomatik olarak mem-search becerisini çağırır
**Mevcut Arama İşlemleri:**
1. **Search Observations** - Gözlemler arasında tam metin arama
2. **Search Sessions** - Oturum özetleri arasında tam metin arama
3. **Search Prompts** - Ham kullanıcı isteklerinde arama
4. **By Concept** - Kavram etiketlerine göre bul (discovery, problem-solution, pattern, vb.)
5. **By File** - Belirli dosyalara referans veren gözlemleri bul
6. **By Type** - Türe göre bul (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Bir proje için yakın zamanlı oturum bağlamını al
8. **Timeline** - Belirli bir zaman noktası etrafındaki birleşik bağlam zaman çizelgesini al
9. **Timeline by Query** - Gözlemleri ara ve en iyi eşleşme etrafındaki zaman çizelgesi bağlamını al
10. **API Help** - Arama API dokümantasyonunu al
**Örnek Doğal Dil Sorguları:**
```
"Geçen oturumda hangi hataları düzelttik?"
"Kimlik doğrulamayı nasıl uyguladık?"
"worker-service.ts dosyasında hangi değişiklikler yapıldı?"
"Bu projedeki son çalışmaları göster"
"Görüntüleyici arayüzünü eklediğimizde ne oluyordu?"
```
Detaylı örnekler için [Arama Araçları Kılavuzu](https://docs.claude-mem.ai/usage/search-tools) bölümüne bakın.
---
## Beta Özellikleri
Claude-Mem, **Endless Mode** (genişletilmiş oturumlar için biyomimetik bellek mimarisi) gibi deneysel özellikler içeren bir **beta kanalı** sunar. http://localhost:37777 → Settings adresindeki web görüntüleyici arayüzünden kararlı ve beta sürümleri arasında geçiş yapın.
Endless Mode hakkında detaylar ve nasıl deneyeceğiniz için **[Beta Özellikleri Dokümantasyonu](https://docs.claude-mem.ai/beta-features)** bölümüne bakın.
---
## Sistem Gereksinimleri
- **Node.js**: 18.0.0 veya üzeri
- **Claude Code**: Plugin desteği olan en son sürüm
- **Bun**: JavaScript çalışma zamanı ve işlem yöneticisi (eksikse otomatik kurulur)
- **uv**: Vektör arama için Python paket yöneticisi (eksikse otomatik kurulur)
- **SQLite 3**: Kalıcı depolama için (dahildir)
---
## Yapılandırma
Ayarlar `~/.claude-mem/settings.json` dosyasında yönetilir (ilk çalıştırmada varsayılanlarla otomatik oluşturulur). AI modelini, worker portunu, veri dizinini, log seviyesini ve bağlam enjeksiyon ayarlarını yapılandırın.
Tüm mevcut ayarlar ve örnekler için **[Yapılandırma Kılavuzu](https://docs.claude-mem.ai/configuration)** bölümüne bakın.
---
## Geliştirme
Derleme talimatları, test etme ve katkı iş akışı için **[Geliştirme Kılavuzu](https://docs.claude-mem.ai/development)** bölümüne bakın.
---
## Sorun Giderme
Sorunlarla karşılaşırsanız, sorunu Claude'a açıklayın ve troubleshoot becerisi otomatik olarak teşhis edip düzeltmeleri sağlayacaktır.
Yaygın sorunlar ve çözümler için **[Sorun Giderme Kılavuzu](https://docs.claude-mem.ai/troubleshooting)** bölümüne bakın.
---
## Hata Raporları
Otomatik oluşturucu ile kapsamlı hata raporları oluşturun:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Katkıda Bulunma
Katkılar memnuniyetle karşılanır! Lütfen:
1. Depoyu fork edin
2. Bir özellik dalı oluşturun
3. Testlerle değişikliklerinizi yapın
4. Dokümantasyonu güncelleyin
5. Pull Request gönderin
Katkı iş akışı için [Geliştirme Kılavuzu](https://docs.claude-mem.ai/development) bölümüne bakın.
---
## Lisans
Bu proje **GNU Affero General Public License v3.0** (AGPL-3.0) altında lisanslanmıştır.
Telif Hakkı (C) 2025 Alex Newman (@thedotmack). Tüm hakları saklıdır.
Tam detaylar için [LICENSE](LICENSE) dosyasına bakın.
**Bu Ne Anlama Gelir:**
- Bu yazılımı özgürce kullanabilir, değiştirebilir ve dağıtabilirsiniz
- Değiştirip bir ağ sunucusunda dağıtırsanız, kaynak kodunuzu kullanılabilir hale getirmelisiniz
- Türev çalışmalar da AGPL-3.0 altında lisanslanmalıdır
- Bu yazılım için HİÇBİR GARANTİ yoktur
**Ragtime Hakkında Not**: `ragtime/` dizini ayrı olarak **PolyForm Noncommercial License 1.0.0** altında lisanslanmıştır. Detaylar için [ragtime/LICENSE](ragtime/LICENSE) dosyasına bakın.
---
## Destek
- **Dokümantasyon**: [docs/](docs/)
- **Sorunlar**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Depo**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Yazar**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDK ile geliştirilmiştir** | **Claude Code ile desteklenmektedir** | **TypeScript ile yapılmıştır**

304
.agent/services/claude-mem/docs/i18n/README.uk.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Це автоматичний переклад. Вітаються виправлення від спільноти!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Система стиснення постійної пам'яті, створена для <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#швидкий-старт">Швидкий старт</a> •
<a href="#як-це-працює">Як це працює</a> •
<a href="#інструменти-пошуку-mcp">Інструменти пошуку</a> •
<a href="#документація">Документація</a> •
<a href="#конфігурація">Конфігурація</a> •
<a href="#усунення-несправностей">Усунення несправностей</a> •
<a href="#ліцензія">Ліцензія</a>
</p>
<p align="center">
Claude-Mem безперешкодно зберігає контекст між сесіями, автоматично фіксуючи спостереження за використанням інструментів, генеруючи семантичні резюме та роблячи їх доступними для майбутніх сесій. Це дозволяє Claude підтримувати безперервність знань про проєкти навіть після завершення або повторного підключення сесій.
</p>
---
## Швидкий старт
Розпочніть нову сесію Claude Code у терміналі та введіть наступні команди:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Перезапустіть Claude Code. Контекст з попередніх сесій автоматично з'явиться в нових сесіях.
**Ключові можливості:**
- 🧠 **Постійна пам'ять** - Контекст зберігається між сесіями
- 📊 **Прогресивне розкриття** - Багаторівневе отримання пам'яті з видимістю вартості токенів
- 🔍 **Пошук на основі навичок** - Запитуйте історію свого проєкту за допомогою навички mem-search
- 🖥️ **Веб-інтерфейс перегляду** - Потік пам'яті в реальному часі на http://localhost:37777
- 💻 **Навичка Claude Desktop** - Шукайте в пам'яті з розмов Claude Desktop
- 🔒 **Контроль конфіденційності** - Використовуйте теги `<private>` для виключення чутливого вмісту зі зберігання
- ⚙️ **Конфігурація контексту** - Детальний контроль над тим, який контекст впроваджується
- 🤖 **Автоматична робота** - Не потребує ручного втручання
- 🔗 **Цитування** - Посилайтеся на минулі спостереження за ідентифікаторами (доступ через http://localhost:37777/api/observation/{id} або перегляд усіх у веб-переглядачі на http://localhost:37777)
- 🧪 **Бета-канал** - Спробуйте експериментальні функції, як-от режим Endless Mode, через перемикання версій
---
## Документація
📚 **[Переглянути повну документацію](https://docs.claude-mem.ai/)** - Переглянути на офіційному сайті
### Початок роботи
- **[Посібник з встановлення](https://docs.claude-mem.ai/installation)** - Швидкий старт і розширене встановлення
- **[Посібник з використання](https://docs.claude-mem.ai/usage/getting-started)** - Як Claude-Mem працює автоматично
- **[Інструменти пошуку](https://docs.claude-mem.ai/usage/search-tools)** - Запитуйте історію свого проєкту природною мовою
- **[Бета-функції](https://docs.claude-mem.ai/beta-features)** - Спробуйте експериментальні функції, як-от режим Endless Mode
### Найкращі практики
- **[Інженерія контексту](https://docs.claude-mem.ai/context-engineering)** - Принципи оптимізації контексту AI-агента
- **[Прогресивне розкриття](https://docs.claude-mem.ai/progressive-disclosure)** - Філософія стратегії підготовки контексту Claude-Mem
### Архітектура
- **[Огляд](https://docs.claude-mem.ai/architecture/overview)** - Компоненти системи та потік даних
- **[Еволюція архітектури](https://docs.claude-mem.ai/architecture-evolution)** - Шлях від v3 до v5
- **[Архітектура хуків](https://docs.claude-mem.ai/hooks-architecture)** - Як Claude-Mem використовує хуки життєвого циклу
- **[Довідник хуків](https://docs.claude-mem.ai/architecture/hooks)** - Пояснення 7 скриптів хуків
- **[Сервіс воркера](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API та управління Bun
- **[База даних](https://docs.claude-mem.ai/architecture/database)** - Схема SQLite та пошук FTS5
- **[Архітектура пошуку](https://docs.claude-mem.ai/architecture/search-architecture)** - Гібридний пошук з векторною базою даних Chroma
### Конфігурація та розробка
- **[Конфігурація](https://docs.claude-mem.ai/configuration)** - Змінні середовища та налаштування
- **[Розробка](https://docs.claude-mem.ai/development)** - Збірка, тестування, внесок
- **[Усунення несправностей](https://docs.claude-mem.ai/troubleshooting)** - Поширені проблеми та рішення
---
## Як це працює
**Основні компоненти:**
1. **5 хуків життєвого циклу** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 скриптів хуків)
2. **Розумне встановлення** - Кешована перевірка залежностей (скрипт перед хуком, не хук життєвого циклу)
3. **Сервіс воркера** - HTTP API на порту 37777 з веб-інтерфейсом перегляду та 10 кінцевими точками пошуку, керується Bun
4. **База даних SQLite** - Зберігає сесії, спостереження, резюме
5. **Навичка mem-search** - Запити природною мовою з прогресивним розкриттям
6. **Векторна база даних Chroma** - Гібридний семантичний + ключовий пошук для інтелектуального отримання контексту
Дивіться [Огляд архітектури](https://docs.claude-mem.ai/architecture/overview) для деталей.
---
## Навичка mem-search
Claude-Mem надає інтелектуальний пошук через навичку mem-search, яка автоматично викликається, коли ви запитуєте про минулу роботу:
**Як це працює:**
- Просто запитайте природно: *"Що ми робили в минулій сесії?"* або *"Ми виправляли цю помилку раніше?"*
- Claude автоматично викликає навичку mem-search для пошуку релевантного контексту
**Доступні операції пошуку:**
1. **Пошук спостережень** - Повнотекстовий пошук у спостереженнях
2. **Пошук сесій** - Повнотекстовий пошук у резюме сесій
3. **Пошук запитів** - Пошук необроблених запитів користувачів
4. **За концепцією** - Знайти за тегами концепцій (discovery, problem-solution, pattern тощо)
5. **За файлом** - Знайти спостереження, що посилаються на конкретні файли
6. **За типом** - Знайти за типом (decision, bugfix, feature, refactor, discovery, change)
7. **Останній контекст** - Отримати останній контекст сесії для проєкту
8. **Часова шкала** - Отримати єдину часову шкалу контексту навколо конкретного моменту часу
9. **Часова шкала за запитом** - Шукати спостереження та отримувати контекст часової шкали навколо найкращого збігу
10. **Довідка API** - Отримати документацію API пошуку
**Приклади запитів природною мовою:**
```
"Які помилки ми виправили в минулій сесії?"
"Як ми реалізували автентифікацію?"
"Які зміни були внесені в worker-service.ts?"
"Покажи мені останню роботу над цим проєктом"
"Що відбувалося, коли ми додали інтерфейс перегляду?"
```
Дивіться [Посібник з інструментів пошуку](https://docs.claude-mem.ai/usage/search-tools) для детальних прикладів.
---
## Бета-функції
Claude-Mem пропонує **бета-канал** з експериментальними функціями, як-от **режим Endless Mode** (біоміметична архітектура пам'яті для тривалих сесій). Перемикайтеся між стабільною та бета-версіями з веб-інтерфейсу перегляду на http://localhost:37777 → Налаштування.
Дивіться **[Документацію бета-функцій](https://docs.claude-mem.ai/beta-features)** для деталей про режим Endless Mode та як його спробувати.
---
## Системні вимоги
- **Node.js**: 18.0.0 або вище
- **Claude Code**: Остання версія з підтримкою плагінів
- **Bun**: Середовище виконання JavaScript та менеджер процесів (автоматично встановлюється, якщо відсутнє)
- **uv**: Менеджер пакетів Python для векторного пошуку (автоматично встановлюється, якщо відсутній)
- **SQLite 3**: Для постійного зберігання (у комплекті)
---
## Конфігурація
Налаштування керуються в `~/.claude-mem/settings.json` (автоматично створюється зі стандартними значеннями при першому запуску). Налаштуйте модель AI, порт воркера, каталог даних, рівень журналювання та параметри впровадження контексту.
Дивіться **[Посібник з конфігурації](https://docs.claude-mem.ai/configuration)** для всіх доступних налаштувань та прикладів.
---
## Розробка
Дивіться **[Посібник з розробки](https://docs.claude-mem.ai/development)** для інструкцій зі збірки, тестування та робочого процесу внеску.
---
## Усунення несправностей
Якщо виникають проблеми, опишіть проблему Claude, і навичка troubleshoot автоматично діагностує та надасть виправлення.
Дивіться **[Посібник з усунення несправностей](https://docs.claude-mem.ai/troubleshooting)** для поширених проблем та рішень.
---
## Звіти про помилки
Створюйте вичерпні звіти про помилки за допомогою автоматизованого генератора:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Внесок
Вітаються внески! Будь ласка:
1. Створіть форк репозиторію
2. Створіть гілку функції
3. Внесіть зміни з тестами
4. Оновіть документацію
5. Надішліть Pull Request
Дивіться [Посібник з розробки](https://docs.claude-mem.ai/development) для робочого процесу внеску.
---
## Ліцензія
Цей проєкт ліцензовано під **GNU Affero General Public License v3.0** (AGPL-3.0).
Авторське право (C) 2025 Alex Newman (@thedotmack). Всі права захищені.
Дивіться файл [LICENSE](LICENSE) для повних деталей.
**Що це означає:**
- Ви можете використовувати, модифікувати та поширювати це програмне забезпечення вільно
- Якщо ви модифікуєте та розгортаєте на мережевому сервері, ви повинні зробити свій вихідний код доступним
- Похідні роботи також повинні бути ліцензовані під AGPL-3.0
- Для цього програмного забезпечення НЕМАЄ ГАРАНТІЇ
**Примітка про Ragtime**: Каталог `ragtime/` ліцензовано окремо під **PolyForm Noncommercial License 1.0.0**. Дивіться [ragtime/LICENSE](ragtime/LICENSE) для деталей.
---
## Підтримка
- **Документація**: [docs/](docs/)
- **Проблеми**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Репозиторій**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Автор**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Створено за допомогою Claude Agent SDK** | **Працює на Claude Code** | **Зроблено з TypeScript**

311
.agent/services/claude-mem/docs/i18n/README.ur.md Normal file
View File

@@ -0,0 +1,311 @@
<section dir="rtl">
🌐 یہ ایک خودکار ترجمہ ہے۔ کمیونٹی کی اصلاحات کا خیر مقدم ہے!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center" dir="ltr">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center"><a href="https://claude.com/claude-code" target="_blank">Claude Code</a> کے لیے بنایا گیا مستقل میموری کمپریشن سسٹم۔</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#تیز-رفتار-شروعات">تیز رفتار شروعات</a> •
<a href="#یہ-کیسے-کام-کرتا-ہے">یہ کیسے کام کرتا ہے</a> •
<a href="#تلاش-کے-اوزار">تلاش کے اوزار</a> •
<a href="#دستاویزات">دستاویزات</a> •
<a href="#ترتیبات">ترتیبات</a> •
<a href="#مسائل-کی-تشخیص">مسائل کی تشخیص</a> •
<a href="#لائسنس">لائسنس</a>
</p>
<p align="center">
Claude-Mem خودکار طور پر ٹول کے استعمال کے بعد کے مشاہدات کو ریکارڈ کرتا ہے، سیمانٹک خلاصے تیار کرتا ہے اور انہیں مستقبل کے سیشنز میں دستیاب کرتا ہے تاکہ آپ سیشن میں براہ راست تناسب محفوظ رہے۔ یہ Claude کو سیشن ختم ہونے یا دوبارہ جڑنے کے بعد بھی منصوبے کے بارے میں معلومات کی مسلسلیت برقرار رکھنے کے قابل بناتا ہے۔
</p>
---
## تیز رفتار شروعات
ٹرمنل میں نیا Claude Code سیشن شروع کریں اور ہیں کمانڈز درج کریں:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Claude Code کو دوبارہ شروع کریں۔ سابقہ سیشن کا تناسب خودکار طور پر نئے سیشن میں موجود ہوگا۔
**اہم خصوصیات:**
- 🧠 **مستقل میموری** - تناسب سیشن کے دوران برقرار رہتا ہے
- 📊 **بتدریج ظہور** - لیئرڈ میموری کی بازیافت ٹوکن کی لاگت کی نمائندگی کے ساتھ
- 🔍 **کمکردہ تلاش** - mem-search مہارت کے ساتھ اپنے منصوبے کی تاریخ میں تلاش کریں
- 🖥️ **ویب ویور یو آئی** - http://localhost:37777 پر حقیقی وقت میموری اسٹریم
- 💻 **Claude Desktop مہارت** - Claude Desktop بات چیت سے میموری تلاش کریں
- 🔒 **رازداری کے کنٹرولز** - حساس مواد کو ذخیرہ سے خارج کرنے کے لیے `<private>` ٹیگ استعمال کریں
- ⚙️ **تناسب کی ترتیبات** - کون سا تناسب انجیکٹ کیا جائے اس پر باریک کنٹرول
- 🤖 **خودکار آپریشن** - کسی دستی مداخلت کی ضرورت نہیں
- 🔗 **حوالہ** - ID کے ذریعے سابقہ مشاہدات کا حوالہ دیں (http://localhost:37777/api/observation/{id} کے ذریعے رسائی حاصل کریں یا تمام کو http://localhost:37777 پر ویب ویور میں دیکھیں)
- 🧪 **بیٹا چینل** - ورژن تبدیل کرنے کے ذریعے Endless Mode جیسی تجرباتی خصوصیات آزمائیں
---
## دستاویزات
📚 **[مکمل دستاویزات دیکھیں](docs/)** - GitHub پر markdown ڈاکس کو براؤز کریں
### شروعات کرنا
- **[انسٹالیشن گائیڈ](https://docs.claude-mem.ai/installation)** - تیز رفتار شروعات اور اعلیٰ درجے کی انسٹالیشن
- **[استعمال گائیڈ](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem خودکار طور پر کیسے کام کرتا ہے
- **[تلاش کے اوزار](https://docs.claude-mem.ai/usage/search-tools)** - قدرتی زبان کے ساتھ اپنے منصوبے کی تاریخ میں تلاش کریں
- **[بیٹا خصوصیات](https://docs.claude-mem.ai/beta-features)** - Endless Mode جیسی تجرباتی خصوصیات آزمائیں
### بہترین طریقہ کار
- **[تناسب انجینیئرنگ](https://docs.claude-mem.ai/context-engineering)** - AI ایجنٹ کے تناسب کی اہمیت کے اصول
- **[بتدریج ظہور](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem کے تناسب کی تیاری کی حکمت عملی کے پیچھے فلسفہ
### تعمیر
- **[جائزہ](https://docs.claude-mem.ai/architecture/overview)** - نظام کے اجزاء اور ڈیٹا کے بہاؤ
- **[تعمیر کا ارتقاء](https://docs.claude-mem.ai/architecture-evolution)** - v3 سے v5 تک کا سفر
- **[ہکس تعمیر](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem لائف سائیکل ہکس کا استعمال کیسے کرتا ہے
- **[ہکس حوالہ](https://docs.claude-mem.ai/architecture/hooks)** - 7 ہک اسکرپٹس کی تشریح
- **[ورکر سروس](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API اور Bun انتظام
- **[ڈیٹا بیس](https://docs.claude-mem.ai/architecture/database)** - SQLite اسکیما اور FTS5 تلاش
- **[تلاش تعمیر](https://docs.claude-mem.ai/architecture/search-architecture)** - Chroma ویکٹر ڈیٹا بیس کے ساتھ ہائبرڈ تلاش
### ترتیبات اور ترقی
- **[ترتیبات](https://docs.claude-mem.ai/configuration)** - ماحول کے متغیرات اور سیٹنگز
- **[ترقی](https://docs.claude-mem.ai/development)** - تعمیر، جانچ، حصہ داری
- **[مسائل کی تشخیص](https://docs.claude-mem.ai/troubleshooting)** - عام مسائل اور حل
---
## یہ کیسے کام کرتا ہے
**اہم اجزاء:**
1. **5 لائف سائیکل ہکس** - SessionStart، UserPromptSubmit، PostToolUse، Stop، SessionEnd (6 ہک اسکرپٹس)
2. **سمارٹ انسٹالیشن** - کیش شدہ منحصرات چیکر (پری ہک اسکرپٹ، لائف سائیکل ہک نہیں)
3. **ورکر سروس** - ویب ویور UI اور 10 تلاش کے endpoints کے ساتھ پورٹ 37777 پر HTTP API، Bun کے ذریعے برتاؤ
4. **SQLite ڈیٹا بیس** - سیشنز، مشاہدات، خلاصہ ذخیرہ کرتا ہے
5. **mem-search مہارت** - بتدریج ظہور کے ساتھ قدرتی زبان کے سوالات
6. **Chroma ویکٹر ڈیٹا بیس** - ہائبرڈ سیمانٹک + کلیدی لفظ تلاش ذہین تناسب کی بازیافت کے لیے
تفصیلات کے لیے [تعمیر کا جائزہ](https://docs.claude-mem.ai/architecture/overview) دیکھیں۔
---
## MCP تلاش کے اوزار
Claude-Mem ٹوکن-موثر **3-لیئر ورک فلو پیٹرن** کی پیروی کرتے ہوئے **4 MCP اوزار** کے ذریعے ذہین میموری تلاش فراہم کرتا ہے:
**3-لیئر ورک فلو:**
1. **`search`** - IDs کے ساتھ کمپیکٹ انڈیکس حاصل کریں (~50-100 ٹوکن/نتیجہ)
2. **`timeline`** - دلچسپ نتائج کے ارد گرد زمانی تناسب حاصل کریں
3. **`get_observations`** - فلٹر شدہ IDs کے لیے صرف مکمل تفصیلات حاصل کریں (~500-1,000 ٹوکن/نتیجہ)
**یہ کیسے کام کرتا ہے:**
- Claude آپ کی میموری میں تلاش کے لیے MCP اوزار استعمال کرتا ہے
- نتائج کا انڈیکس حاصل کرنے کے لیے `search` سے شروع کریں
- مخصوص مشاہدات کے ارد گرد کیا ہو رہا تھا دیکھنے کے لیے `timeline` استعمال کریں
- متعلقہ IDs کے لیے مکمل تفصیلات حاصل کرنے کے لیے `get_observations` استعمال کریں
- تفصیلات حاصل کرنے سے پہلے فلٹرنگ کے ذریعے **~10x ٹوکن کی بچت**
**دستیاب MCP اوزار:**
1. **`search`** - مکمل متن کی تلاش کے سوالات کے ساتھ میموری انڈیکس تلاش کریں، قسم/تاریخ/منصوبے کے لحاظ سے فلٹر کریں
2. **`timeline`** - مخصوص مشاہدہ یا سوال کے ارد گرد زمانی تناسب حاصل کریں
3. **`get_observations`** - IDs کے ذریعے مکمل مشاہدہ تفصیلات حاصل کریں (ہمیشہ متعدد IDs کو بیچ کریں)
4. **`__IMPORTANT`** - ورک فلو دستاویزات (ہمیشہ Claude کو نظر آتی ہے)
**استعمال کی مثال:**
```typescript
// مرحلہ 1: انڈیکس کے لیے تلاش کریں
search(query="authentication bug", type="bugfix", limit=10)
// مرحلہ 2: انڈیکس کا جائزہ لیں، متعلقہ IDs کی شناخت کریں (مثلاً، #123, #456)
// مرحلہ 3: مکمل تفصیلات حاصل کریں
get_observations(ids=[123, 456])
```
تفصیلی مثالوں کے لیے [تلاش کے اوزار گائیڈ](https://docs.claude-mem.ai/usage/search-tools) دیکھیں۔
---
## بیٹا خصوصیات
Claude-Mem ایک **بیٹا چینل** فراہم کرتا ہے جس میں **Endless Mode** جیسی تجرباتی خصوصیات ہیں (بڑھی ہوئی سیشنز کے لیے حیاتی نقل میموری کی تعمیر)۔ http://localhost:37777 → Settings میں ویب ویور UI سے مستحکم اور بیٹا ورژن کے درمیان سوئچ کریں۔
Endless Mode اور اسے کیسے آزمائیں اس کے بارے میں تفصیلات کے لیے **[بیٹا خصوصیات دستاویزات](https://docs.claude-mem.ai/beta-features)** دیکھیں۔
---
## نظام کی ضروریات
- **Node.js**: 18.0.0 یا اس سے اوپر
- **Claude Code**: پلگ ان سپورٹ کے ساتھ جدید ترین ورژن
- **Bun**: JavaScript رن ٹائم اور پروسیس مینیجر (غیر موجود ہو تو خودکار طور پر انسٹال ہوگا)
- **uv**: ویکٹر تلاش کے لیے Python پیکج مینیجر (غیر موجود ہو تو خودکار طور پر انسٹال ہوگا)
- **SQLite 3**: مستقل اسٹوریج کے لیے (بنڈل شدہ)
---
## ترتیبات
سیٹنگز `~/.claude-mem/settings.json` میں منظم ہیں (پہلی رن میں ڈیفالٹ کے ساتھ خودکار طور پر بنائی جاتی ہے)۔ AI ماڈل، ورکر پورٹ، ڈیٹا ڈائریکٹری، لاگ لیول اور تناسب انجیکشن سیٹنگز کو ترتیب دیں۔
تمام دستیاب سیٹنگز اور مثالوں کے لیے **[ترتیبات گائیڈ](https://docs.claude-mem.ai/configuration)** دیکھیں۔
---
## ترقی
تعمیر کی ہدایات، جانچ اور حصہ داری کے کام کے بہاؤ کے لیے **[ترقی گائیڈ](https://docs.claude-mem.ai/development)** دیکھیں۔
---
## مسائل کی تشخیص
اگر مسائل کا سامنا ہو تو Claude کو مسئلہ بتائیں اور troubleshoot مہارت خودکار طور پر تشخیص دے گی اور حل فراہم کرے گی۔
عام مسائل اور حل کے لیے **[مسائل کی تشخیص گائیڈ](https://docs.claude-mem.ai/troubleshooting)** دیکھیں۔
---
## خرابی کی رپورٹ
خودکار جنریٹر کے ساتھ تفصیلی خرابی کی رپورٹ تیار کریں:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## حصہ داری
حصہ داری کا خیر مقدم ہے! براہ کرم:
1. رپوزیٹری کو فورک کریں
2. ایک خصوصیت کی برانچ بنائیں
3. ٹیسٹ کے ساتھ اپنی تبدیلیاں کریں
4. دستاویزات کو اپڈیٹ کریں
5. ایک Pull Request جمع کریں
حصہ داری کے کام کے بہاؤ کے لیے [ترقی گائیڈ](https://docs.claude-mem.ai/development) دیکھیں۔
---
## لائسنس
یہ منصوبہ **GNU Affero General Public License v3.0** (AGPL-3.0) کے تحت لائسنس ہے۔
Copyright (C) 2025 Alex Newman (@thedotmack)۔ تمام حقوق محفوظ ہیں۔
مکمل تفصیلات کے لیے [LICENSE](LICENSE) فائل دیکھیں۔
**اس کا مطلب کیا ہے:**
- آپ اس سافٹ ویئر کو آزادی سے استعمال، تبدیل اور تقسیم کر سکتے ہیں
- اگر آپ اسے تبدیل کریں اور نیٹ ورک سرور میں نشر کریں تو آپ کو اپنا سورس کوڈ دستیاب کرنا ہوگا
- ماخوذ کام بھی AGPL-3.0 کے تحت لائسنس ہونے چاہیں
- اس سافٹ ویئر کے لیے کوئی وارنٹی نہیں
**Ragtime کے بارے میں نوٹ**: `ragtime/` ڈائریکٹری الگ سے **PolyForm Noncommercial License 1.0.0** کے تحت لائسنس ہے۔ تفصیلات کے لیے [ragtime/LICENSE](ragtime/LICENSE) دیکھیں۔
---
## معاونت
- **دستاویزات**: [docs/](docs/)
- **مسائل**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **رپوزیٹری**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **مصنف**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Claude Agent SDK کے ساتھ بنایا گیا** | **Claude Code کے ذریعے طاقت ور** | **TypeScript کے ساتھ بنایا گیا**
</section>

304
.agent/services/claude-mem/docs/i18n/README.vi.md Normal file
View File

@@ -0,0 +1,304 @@
🌐 Đây là bản dịch tự động. Chúng tôi hoan nghênh các đóng góp từ cộng đồng!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Hệ thống nén bộ nhớ liên tục được xây dựng cho <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#bắt-đầu-nhanh">Bắt Đầu Nhanh</a> •
<a href="#cách-hoạt-động">Cách Hoạt Động</a> •
<a href="#công-cụ-tìm-kiếm-mcp">Công Cụ Tìm Kiếm</a> •
<a href="#tài-liệu">Tài Liệu</a> •
<a href="#cấu-hình">Cấu Hình</a> •
<a href="#khắc-phục-sự-cố">Khắc Phục Sự Cố</a> •
<a href="#giấy-phép">Giấy Phép</a>
</p>
<p align="center">
Claude-Mem duy trì ngữ cảnh liền mạch qua các phiên làm việc bằng cách tự động ghi lại các quan sát về việc sử dụng công cụ, tạo tóm tắt ngữ nghĩa và cung cấp chúng cho các phiên làm việc trong tương lai. Điều này giúp Claude duy trì tính liên tục của kiến thức về các dự án ngay cả sau khi phiên làm việc kết thúc hoặc kết nối lại.
</p>
---
## Bắt Đầu Nhanh
Bắt đầu một phiên Claude Code mới trong terminal và nhập các lệnh sau:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Khởi động lại Claude Code. Ngữ cảnh từ các phiên trước sẽ tự động xuất hiện trong các phiên mới.
**Tính Năng Chính:**
- 🧠 **Bộ Nhớ Liên Tục** - Ngữ cảnh được lưu giữ qua các phiên làm việc
- 📊 **Tiết Lộ Tuần Tự** - Truy xuất bộ nhớ theo lớp với khả năng hiển thị chi phí token
- 🔍 **Tìm Kiếm Theo Kỹ Năng** - Truy vấn lịch sử dự án với kỹ năng mem-search
- 🖥️ **Giao Diện Web Viewer** - Luồng bộ nhớ thời gian thực tại http://localhost:37777
- 💻 **Kỹ Năng Claude Desktop** - Tìm kiếm bộ nhớ từ các cuộc trò chuyện Claude Desktop
- 🔒 **Kiểm Soát Quyền Riêng Tư** - Sử dụng thẻ `<private>` để loại trừ nội dung nhạy cảm khỏi lưu trữ
- ⚙️ **Cấu Hình Ngữ Cảnh** - Kiểm soát chi tiết về ngữ cảnh được chèn vào
- 🤖 **Hoạt Động Tự Động** - Không cần can thiệp thủ công
- 🔗 **Trích Dẫn** - Tham chiếu các quan sát trong quá khứ với ID (truy cập qua http://localhost:37777/api/observation/{id} hoặc xem tất cả trong web viewer tại http://localhost:37777)
- 🧪 **Kênh Beta** - Dùng thử các tính năng thử nghiệm như Endless Mode thông qua chuyển đổi phiên bản
---
## Tài Liệu
📚 **[Xem Tài Liệu Đầy Đủ](https://docs.claude-mem.ai/)** - Duyệt trên trang web chính thức
### Bắt Đầu
- **[Hướng Dẫn Cài Đặt](https://docs.claude-mem.ai/installation)** - Bắt đầu nhanh & cài đặt nâng cao
- **[Hướng Dẫn Sử Dụng](https://docs.claude-mem.ai/usage/getting-started)** - Cách Claude-Mem hoạt động tự động
- **[Công Cụ Tìm Kiếm](https://docs.claude-mem.ai/usage/search-tools)** - Truy vấn lịch sử dự án bằng ngôn ngữ tự nhiên
- **[Tính Năng Beta](https://docs.claude-mem.ai/beta-features)** - Dùng thử các tính năng thử nghiệm như Endless Mode
### Thực Hành Tốt Nhất
- **[Kỹ Thuật Ngữ Cảnh](https://docs.claude-mem.ai/context-engineering)** - Các nguyên tắc tối ưu hóa ngữ cảnh cho AI agent
- **[Tiết Lộ Tuần Tự](https://docs.claude-mem.ai/progressive-disclosure)** - Triết lý đằng sau chiến lược chuẩn bị ngữ cảnh của Claude-Mem
### Kiến Trúc
- **[Tổng Quan](https://docs.claude-mem.ai/architecture/overview)** - Các thành phần hệ thống & luồng dữ liệu
- **[Phát Triển Kiến Trúc](https://docs.claude-mem.ai/architecture-evolution)** - Hành trình từ v3 đến v5
- **[Kiến Trúc Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Cách Claude-Mem sử dụng lifecycle hooks
- **[Tham Chiếu Hooks](https://docs.claude-mem.ai/architecture/hooks)** - Giải thích 7 hook scripts
- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & quản lý Bun
- **[Cơ Sở Dữ Liệu](https://docs.claude-mem.ai/architecture/database)** - Schema SQLite & tìm kiếm FTS5
- **[Kiến Trúc Tìm Kiếm](https://docs.claude-mem.ai/architecture/search-architecture)** - Tìm kiếm kết hợp với cơ sở dữ liệu vector Chroma
### Cấu Hình & Phát Triển
- **[Cấu Hình](https://docs.claude-mem.ai/configuration)** - Biến môi trường & cài đặt
- **[Phát Triển](https://docs.claude-mem.ai/development)** - Xây dựng, kiểm thử, đóng góp
- **[Khắc Phục Sự Cố](https://docs.claude-mem.ai/troubleshooting)** - Các vấn đề thường gặp & giải pháp
---
## Cách Hoạt Động
**Các Thành Phần Cốt Lõi:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. **Smart Install** - Công cụ kiểm tra phụ thuộc được cache (pre-hook script, không phải lifecycle hook)
3. **Worker Service** - HTTP API trên cổng 37777 với giao diện web viewer và 10 điểm cuối tìm kiếm, được quản lý bởi Bun
4. **SQLite Database** - Lưu trữ các phiên, quan sát, tóm tắt
5. **mem-search Skill** - Truy vấn ngôn ngữ tự nhiên với tiết lộ tuần tự
6. **Chroma Vector Database** - Tìm kiếm kết hợp ngữ nghĩa + từ khóa để truy xuất ngữ cảnh thông minh
Xem [Tổng Quan Kiến Trúc](https://docs.claude-mem.ai/architecture/overview) để biết chi tiết.
---
## mem-search Skill
Claude-Mem cung cấp tìm kiếm thông minh thông qua kỹ năng mem-search tự động kích hoạt khi bạn hỏi về công việc trước đây:
**Cách Hoạt Động:**
- Chỉ cần hỏi một cách tự nhiên: *"Chúng ta đã làm gì trong phiên trước?"* hoặc *"Chúng ta đã sửa lỗi này trước đây chưa?"*
- Claude tự động gọi kỹ năng mem-search để tìm ngữ cảnh liên quan
**Các Thao Tác Tìm Kiếm Có Sẵn:**
1. **Search Observations** - Tìm kiếm toàn văn trên các quan sát
2. **Search Sessions** - Tìm kiếm toàn văn trên các tóm tắt phiên
3. **Search Prompts** - Tìm kiếm các yêu cầu người dùng thô
4. **By Concept** - Tìm theo thẻ khái niệm (discovery, problem-solution, pattern, v.v.)
5. **By File** - Tìm các quan sát tham chiếu đến các tệp cụ thể
6. **By Type** - Tìm theo loại (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Lấy ngữ cảnh phiên gần đây cho một dự án
8. **Timeline** - Lấy dòng thời gian thống nhất của ngữ cảnh xung quanh một thời điểm cụ thể
9. **Timeline by Query** - Tìm kiếm các quan sát và lấy ngữ cảnh dòng thời gian xung quanh kết quả khớp tốt nhất
10. **API Help** - Lấy tài liệu API tìm kiếm
**Ví Dụ Truy Vấn Ngôn Ngữ Tự Nhiên:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
Xem [Hướng Dẫn Công Cụ Tìm Kiếm](https://docs.claude-mem.ai/usage/search-tools) để biết các ví dụ chi tiết.
---
## Tính Năng Beta
Claude-Mem cung cấp **kênh beta** với các tính năng thử nghiệm như **Endless Mode** (kiến trúc bộ nhớ sinh học mô phỏng cho các phiên mở rộng). Chuyển đổi giữa các phiên bản ổn định và beta từ giao diện web viewer tại http://localhost:37777 → Settings.
Xem **[Tài Liệu Tính Năng Beta](https://docs.claude-mem.ai/beta-features)** để biết chi tiết về Endless Mode và cách dùng thử.
---
## Yêu Cầu Hệ Thống
- **Node.js**: 18.0.0 hoặc cao hơn
- **Claude Code**: Phiên bản mới nhất với hỗ trợ plugin
- **Bun**: JavaScript runtime và trình quản lý tiến trình (tự động cài đặt nếu thiếu)
- **uv**: Trình quản lý gói Python cho tìm kiếm vector (tự động cài đặt nếu thiếu)
- **SQLite 3**: Cho lưu trữ liên tục (đi kèm)
---
## Cấu Hình
Cài đặt được quản lý trong `~/.claude-mem/settings.json` (tự động tạo với giá trị mặc định khi chạy lần đầu). Cấu hình mô hình AI, cổng worker, thư mục dữ liệu, mức độ log và cài đặt chèn ngữ cảnh.
Xem **[Hướng Dẫn Cấu Hình](https://docs.claude-mem.ai/configuration)** để biết tất cả các cài đặt và ví dụ có sẵn.
---
## Phát Triển
Xem **[Hướng Dẫn Phát Triển](https://docs.claude-mem.ai/development)** để biết hướng dẫn xây dựng, kiểm thử và quy trình đóng góp.
---
## Khắc Phục Sự Cố
Nếu gặp sự cố, hãy mô tả vấn đề cho Claude và kỹ năng troubleshoot sẽ tự động chẩn đoán và cung cấp các bản sửa lỗi.
Xem **[Hướng Dẫn Khắc Phục Sự Cố](https://docs.claude-mem.ai/troubleshooting)** để biết các vấn đề thường gặp và giải pháp.
---
## Báo Cáo Lỗi
Tạo báo cáo lỗi toàn diện với trình tạo tự động:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Đóng Góp
Chúng tôi hoan nghênh các đóng góp! Vui lòng:
1. Fork repository
2. Tạo nhánh tính năng
3. Thực hiện thay đổi của bạn kèm kiểm thử
4. Cập nhật tài liệu
5. Gửi Pull Request
Xem [Hướng Dẫn Phát Triển](https://docs.claude-mem.ai/development) để biết quy trình đóng góp.
---
## Giấy Phép
Dự án này được cấp phép theo **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Bảo lưu mọi quyền.
Xem tệp [LICENSE](LICENSE) để biết chi tiết đầy đủ.
**Điều Này Có Nghĩa Là:**
- Bạn có thể sử dụng, sửa đổi và phân phối phần mềm này tự do
- Nếu bạn sửa đổi và triển khai trên máy chủ mạng, bạn phải cung cấp mã nguồn của mình
- Các tác phẩm phái sinh cũng phải được cấp phép theo AGPL-3.0
- KHÔNG CÓ BẢO HÀNH cho phần mềm này
**Lưu Ý Về Ragtime**: Thư mục `ragtime/` được cấp phép riêng theo **PolyForm Noncommercial License 1.0.0**. Xem [ragtime/LICENSE](ragtime/LICENSE) để biết chi tiết.
---
## Hỗ Trợ
- **Tài Liệu**: [docs/](docs/)
- **Vấn Đề**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Tác Giả**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Được Xây Dựng với Claude Agent SDK** | **Được Hỗ Trợ bởi Claude Code** | **Được Tạo với TypeScript**

311
.agent/services/claude-mem/docs/i18n/README.zh-tw.md Normal file
View File

@@ -0,0 +1,311 @@
🌐 這是自動翻譯。歡迎社群貢獻修正！
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">為 <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> 打造的持久記憶壓縮系統</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#快速開始">快速開始</a> •
<a href="#運作原理">運作原理</a> •
<a href="#mcp-搜尋工具">搜尋工具</a> •
<a href="#文件">文件</a> •
<a href="#設定">設定</a> •
<a href="#疑難排解">疑難排解</a> •
<a href="#授權條款">授權條款</a>
</p>
<p align="center">
Claude-Mem 透過自動擷取工具使用觀察、產生語意摘要並在未來的工作階段中提供使用，無縫保留跨工作階段的脈絡。這使 Claude 即使在工作階段結束或重新連線後，仍能維持對專案的知識連續性。
</p>
---
## 快速開始
在終端機中開啟新的 Claude Code 工作階段，並輸入以下指令：
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
重新啟動 Claude Code。先前工作階段的脈絡將自動出現在新的工作階段中。
**主要功能：**
- 🧠 **持久記憶** - 脈絡跨工作階段保留
- 📊 **漸進式揭露** - 具有 Token 成本可見性的分層記憶擷取
- 🔍 **技能式搜尋** - 使用 mem-search 技能查詢專案歷史
- 🖥️ **網頁檢視介面** - 在 http://localhost:37777 即時檢視記憶串流
- 💻 **Claude Desktop 技能** - 從 Claude Desktop 對話中搜尋記憶
- 🔒 **隱私控制** - 使用 `<private>` 標籤排除敏感內容的儲存
- ⚙️ **脈絡設定** - 精細控制注入哪些脈絡
- 🤖 **自動運作** - 無需手動介入
- 🔗 **引用** - 使用 ID 參考過去的觀察（透過 http://localhost:37777/api/observation/{id} 存取，或在 http://localhost:37777 的網頁檢視器中檢視全部）
- 🧪 **Beta 通道** - 透過版本切換試用 Endless Mode 等實驗性功能
---
## 文件
📚 **[檢視完整文件](docs/)** - 在 GitHub 上瀏覽 Markdown 文件
### 入門指南
- **[安裝指南](https://docs.claude-mem.ai/installation)** - 快速開始與進階安裝
- **[使用指南](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem 如何自動運作
- **[搜尋工具](https://docs.claude-mem.ai/usage/search-tools)** - 使用自然語言查詢專案歷史
- **[Beta 功能](https://docs.claude-mem.ai/beta-features)** - 試用 Endless Mode 等實驗性功能
### 最佳實務
- **[脈絡工程](https://docs.claude-mem.ai/context-engineering)** - AI 代理脈絡最佳化原則
- **[漸進式揭露](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem 脈絡啟動策略背後的理念
### 架構
- **[概覽](https://docs.claude-mem.ai/architecture/overview)** - 系統元件與資料流程
- **[架構演進](https://docs.claude-mem.ai/architecture-evolution)** - 從 v3 到 v5 的旅程
- **[Hooks 架構](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem 如何使用生命週期掛鉤
- **[Hooks 參考](https://docs.claude-mem.ai/architecture/hooks)** - 7 個掛鉤腳本說明
- **[Worker 服務](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API 與 Bun 管理
- **[資料庫](https://docs.claude-mem.ai/architecture/database)** - SQLite 結構描述與 FTS5 搜尋
- **[搜尋架構](https://docs.claude-mem.ai/architecture/search-architecture)** - 使用 Chroma 向量資料庫的混合搜尋
### 設定與開發
- **[設定](https://docs.claude-mem.ai/configuration)** - 環境變數與設定
- **[開發](https://docs.claude-mem.ai/development)** - 建置、測試、貢獻
- **[疑難排解](https://docs.claude-mem.ai/troubleshooting)** - 常見問題與解決方案
---
## 運作原理
**核心元件：**
1. **5 個生命週期掛鉤** - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 個掛鉤腳本）
2. **智慧安裝** - 快取的相依性檢查器（pre-hook 腳本，非生命週期掛鉤）
3. **Worker 服務** - 連接埠 37777 上的 HTTP API，含網頁檢視介面與 10 個搜尋端點，由 Bun 管理
4. **SQLite 資料庫** - 儲存工作階段、觀察、摘要
5. **mem-search 技能** - 具有漸進式揭露的自然語言查詢
6. **Chroma 向量資料庫** - 用於智慧脈絡擷取的混合語意 + 關鍵字搜尋
詳情請參閱[架構概覽](https://docs.claude-mem.ai/architecture/overview)。
---
## MCP 搜尋工具
Claude-Mem 透過遵循 Token 高效的 **3 層工作流程模式**，以 **4 個 MCP 工具**提供智慧記憶搜尋：
**3 層工作流程：**
1. **`search`** - 取得精簡索引與 ID（每筆結果約 50-100 tokens）
2. **`timeline`** - 取得有趣結果周圍的時間脈絡
3. **`get_observations`** - 僅為過濾後的 ID 擷取完整詳情（每筆結果約 500-1,000 tokens）
**運作方式：**
- Claude 使用 MCP 工具搜尋您的記憶
- 從 `search` 開始取得結果索引
- 使用 `timeline` 檢視特定觀察周圍發生的事情
- 使用 `get_observations` 擷取相關 ID 的完整詳情
- 透過在擷取詳情前過濾，**節省約 10 倍 token**
**可用的 MCP 工具：**
1. **`search`** - 使用全文查詢搜尋記憶索引，依類型/日期/專案過濾
2. **`timeline`** - 取得特定觀察或查詢周圍的時間脈絡
3. **`get_observations`** - 依 ID 擷取完整觀察詳情（批次處理多個 ID）
4. **`__IMPORTANT`** - 工作流程文件（Claude 永遠可見）
**使用範例：**
```typescript
// 步驟 1：搜尋索引
search(query="authentication bug", type="bugfix", limit=10)
// 步驟 2：檢閱索引，識別相關 ID（例如 #123、#456）
// 步驟 3：擷取完整詳情
get_observations(ids=[123, 456])
```
詳細範例請參閱[搜尋工具指南](https://docs.claude-mem.ai/usage/search-tools)。
---
## Beta 功能
Claude-Mem 提供具有實驗性功能的 **Beta 通道**，例如 **Endless Mode**（用於延長工作階段的仿生記憶架構）。在 http://localhost:37777 → Settings 的網頁檢視介面中切換穩定版與 Beta 版。
有關 Endless Mode 與如何試用的詳情，請參閱 **[Beta 功能文件](https://docs.claude-mem.ai/beta-features)**。
---
## 系統需求
- **Node.js**：18.0.0 或更高版本
- **Claude Code**：具有外掛支援的最新版本
- **Bun**：JavaScript 執行環境與程序管理員（如缺少將自動安裝）
- **uv**：用於向量搜尋的 Python 套件管理員（如缺少將自動安裝）
- **SQLite 3**：用於持久儲存（已內建）
---
## 設定
設定在 `~/.claude-mem/settings.json` 中管理（首次執行時自動以預設值建立）。設定 AI 模型、Worker 連接埠、資料目錄、日誌層級與脈絡注入設定。
所有可用設定與範例請參閱 **[設定指南](https://docs.claude-mem.ai/configuration)**。
---
## 開發
建置說明、測試與貢獻工作流程請參閱 **[開發指南](https://docs.claude-mem.ai/development)**。
---
## 疑難排解
如遇問題，向 Claude 描述問題，troubleshoot 技能將自動診斷並提供修正。
常見問題與解決方案請參閱 **[疑難排解指南](https://docs.claude-mem.ai/troubleshooting)**。
---
## 錯誤回報
使用自動產生器建立完整的錯誤回報：
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## 貢獻
歡迎貢獻！請依照以下步驟：
1. Fork 儲存庫
2. 建立功能分支
3. 加入測試並進行變更
4. 更新文件
5. 提交 Pull Request
貢獻工作流程請參閱[開發指南](https://docs.claude-mem.ai/development)。
---
## 授權條款
本專案採用 **GNU Affero 通用公共授權條款 v3.0**（AGPL-3.0）授權。
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
完整詳情請參閱 [LICENSE](LICENSE) 檔案。
**這代表什麼：**
- 您可以自由使用、修改與散佈此軟體
- 如果您修改並部署於網路伺服器上，您必須公開您的原始碼
- 衍生作品也必須採用 AGPL-3.0 授權
- 本軟體不提供任何擔保
**關於 Ragtime 的說明**：`ragtime/` 目錄採用 **PolyForm Noncommercial License 1.0.0** 另行授權。詳情請參閱 [ragtime/LICENSE](ragtime/LICENSE)。
---
## 支援
- **文件**：[docs/](docs/)
- **Issues**：[GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **儲存庫**：[github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **官方 X 帳號**：[@Claude_Memory](https://x.com/Claude_Memory)
- **官方 Discord**：[加入 Discord](https://discord.com/invite/J4wttp9vDu)
- **作者**：Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**使用 Claude Agent SDK 建置** | **由 Claude Code 驅動** | **以 TypeScript 開發**

306
.agent/services/claude-mem/docs/i18n/README.zh.md Normal file
View File

@@ -0,0 +1,306 @@
🌐 这是自动翻译。欢迎社区修正!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt-br.md">🇧🇷 Português</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">为 <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> 构建的持久化内存压缩系统。</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#快速开始">快速开始</a> •
<a href="#工作原理">工作原理</a> •
<a href="#mcp-搜索工具">搜索工具</a> •
<a href="#文档">文档</a> •
<a href="#配置">配置</a> •
<a href="#故障排除">故障排除</a> •
<a href="#许可证">许可证</a>
</p>
<p align="center">
Claude-Mem 通过自动捕获工具使用观察、生成语义摘要并使其可用于未来会话,无缝保留跨会话的上下文。这使 Claude 能够在会话结束或重新连接后仍保持对项目的知识连续性。
</p>
---
## 快速开始
在终端中启动新的 Claude Code 会话并输入以下命令:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
重启 Claude Code。来自先前会话的上下文将自动出现在新会话中。
**核心特性:**
- 🧠 **持久化内存** - 上下文跨会话保留
- 📊 **渐进式披露** - 分层内存检索,具有令牌成本可见性
- 🔍 **基于技能的搜索** - 使用 mem-search 技能查询项目历史
- 🖥️ **Web 查看器界面** - 在 http://localhost:37777 实时查看内存流
- 💻 **Claude Desktop 技能** - 从 Claude Desktop 对话中搜索内存
- 🔒 **隐私控制** - 使用 `<private>` 标签排除敏感内容的存储
- ⚙️ **上下文配置** - 精细控制注入的上下文内容
- 🤖 **自动操作** - 无需手动干预
- 🔗 **引用** - 使用 ID 引用过去的观察(通过 http://localhost:37777/api/observation/{id} 访问,或在 http://localhost:37777 的 Web 查看器中查看全部)
- 🧪 **测试版渠道** - 通过版本切换尝试实验性功能,如无尽模式
---
## 文档
📚 **[查看完整文档](https://docs.claude-mem.ai/)** - 在官方网站浏览
### 入门指南
- **[安装指南](https://docs.claude-mem.ai/installation)** - 快速开始与高级安装
- **[使用指南](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem 如何自动工作
- **[搜索工具](https://docs.claude-mem.ai/usage/search-tools)** - 使用自然语言查询项目历史
- **[测试版功能](https://docs.claude-mem.ai/beta-features)** - 尝试实验性功能,如无尽模式
### 最佳实践
- **[上下文工程](https://docs.claude-mem.ai/context-engineering)** - AI 代理上下文优化原则
- **[渐进式披露](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem 上下文启动策略背后的哲学
### 架构
- **[概述](https://docs.claude-mem.ai/architecture/overview)** - 系统组件与数据流
- **[架构演进](https://docs.claude-mem.ai/architecture-evolution)** - 从 v3 到 v5 的旅程
- **[钩子架构](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem 如何使用生命周期钩子
- **[钩子参考](https://docs.claude-mem.ai/architecture/hooks)** - 7 个钩子脚本详解
- **[Worker 服务](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API 与 Bun 管理
- **[数据库](https://docs.claude-mem.ai/architecture/database)** - SQLite 模式与 FTS5 搜索
- **[搜索架构](https://docs.claude-mem.ai/architecture/search-architecture)** - 使用 Chroma 向量数据库的混合搜索
### 配置与开发
- **[配置](https://docs.claude-mem.ai/configuration)** - 环境变量与设置
- **[开发](https://docs.claude-mem.ai/development)** - 构建、测试、贡献
- **[故障排除](https://docs.claude-mem.ai/troubleshooting)** - 常见问题与解决方案
---
## 工作原理
**核心组件:**
1. **5 个生命周期钩子** - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd(6 个钩子脚本)
2. **智能安装** - 缓存依赖检查器(预钩子脚本,不是生命周期钩子)
3. **Worker 服务** - 在端口 37777 上的 HTTP API,带有 Web 查看器界面和 10 个搜索端点,由 Bun 管理
4. **SQLite 数据库** - 存储会话、观察、摘要
5. **mem-search 技能** - 具有渐进式披露的自然语言查询
6. **Chroma 向量数据库** - 混合语义 + 关键词搜索,实现智能上下文检索
详见[架构概述](https://docs.claude-mem.ai/architecture/overview)。
---
## mem-search 技能
Claude-Mem 通过 mem-search 技能提供智能搜索,当您询问过去的工作时会自动调用:
**工作方式:**
- 只需自然提问:*"上次会话我们做了什么?"* 或 *"我们之前修复过这个 bug 吗?"*
- Claude 自动调用 mem-search 技能查找相关上下文
**可用搜索操作:**
1. **搜索观察** - 跨观察的全文搜索
2. **搜索会话** - 跨会话摘要的全文搜索
3. **搜索提示** - 搜索原始用户请求
4. **按概念搜索** - 按概念标签查找(发现、问题-解决方案、模式等)
5. **按文件搜索** - 查找引用特定文件的观察
6. **按类型搜索** - 按类型查找(决策、bug修复、功能、重构、发现、更改)
7. **最近上下文** - 获取项目的最近会话上下文
8. **时间线** - 获取特定时间点周围的统一上下文时间线
9. **按查询的时间线** - 搜索观察并获取最佳匹配周围的时间线上下文
10. **API 帮助** - 获取搜索 API 文档
**自然语言查询示例:**
```
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
```
详见[搜索工具指南](https://docs.claude-mem.ai/usage/search-tools)的详细示例。
---
## 测试版功能
Claude-Mem 提供**测试版渠道**,包含实验性功能,如**无尽模式**(用于扩展会话的仿生记忆架构)。从 Web 查看器界面 http://localhost:37777 → 设置 切换稳定版和测试版。
详见 **[测试版功能文档](https://docs.claude-mem.ai/beta-features)** 了解无尽模式的详细信息和试用方法。
---
## 系统要求
- **Node.js**: 18.0.0 或更高版本
- **Claude Code**: 支持插件的最新版本
- **Bun**: JavaScript 运行时和进程管理器(如缺失会自动安装)
- **uv**: 用于向量搜索的 Python 包管理器(如缺失会自动安装)
- **SQLite 3**: 用于持久化存储(已内置)
---
## 配置
设置在 `~/.claude-mem/settings.json` 中管理(首次运行时自动创建默认设置)。可配置 AI 模型、worker 端口、数据目录、日志级别和上下文注入设置。
详见 **[配置指南](https://docs.claude-mem.ai/configuration)** 了解所有可用设置和示例。
---
## 开发
详见 **[开发指南](https://docs.claude-mem.ai/development)** 了解构建说明、测试和贡献工作流程。
---
## 故障排除
如果遇到问题,向 Claude 描述问题,troubleshoot 技能将自动诊断并提供修复方案。
详见 **[故障排除指南](https://docs.claude-mem.ai/troubleshooting)** 了解常见问题和解决方案。
---
## Bug 报告
使用自动生成器创建全面的 bug 报告:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## 贡献
欢迎贡献!请:
1. Fork 仓库
2. 创建功能分支
3. 进行更改并添加测试
4. 更新文档
5. 提交 Pull Request
详见[开发指南](https://docs.claude-mem.ai/development)了解贡献工作流程。
---
## 许可证
本项目采用 **GNU Affero General Public License v3.0** (AGPL-3.0) 许可。
Copyright (C) 2025 Alex Newman (@thedotmack)。保留所有权利。
详见 [LICENSE](LICENSE) 文件了解完整详情。
**这意味着什么:**
- 您可以自由使用、修改和分发本软件
- 如果您修改并部署到网络服务器上,必须公开您的源代码
- 衍生作品也必须采用 AGPL-3.0 许可
- 本软件不提供任何保证
**关于 Ragtime 的说明**: `ragtime/` 目录单独采用 **PolyForm Noncommercial License 1.0.0** 许可。详见 [ragtime/LICENSE](ragtime/LICENSE)。
---
## 支持
- **文档**: [docs/](docs/)
- **问题反馈**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **仓库**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **作者**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**使用 Claude Agent SDK 构建** | **由 Claude Code 驱动** | **使用 TypeScript 制作**
---

305
.agent/services/claude-mem/docs/i18n/pt.md Normal file
View File

@@ -0,0 +1,305 @@
🌐 Esta é uma tradução manual por mig4ng. Correções da comunidade são bem-vindas!
---
<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>
<p align="center">
<a href="README.zh.md">🇨🇳 中文</a> •
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="README.ja.md">🇯🇵 日本語</a> •
<a href="README.pt.md">🇵🇹 Português</a> •
<a href="README.pt-br.md">🇧🇷 Português (Brasil)</a> •
<a href="README.ko.md">🇰🇷 한국어</a> •
<a href="README.es.md">🇪🇸 Español</a> •
<a href="README.de.md">🇩🇪 Deutsch</a> •
<a href="README.fr.md">🇫🇷 Français</a>
<a href="README.he.md">🇮🇱 עברית</a> •
<a href="README.ar.md">🇸🇦 العربية</a> •
<a href="README.ru.md">🇷🇺 Русский</a> •
<a href="README.pl.md">🇵🇱 Polski</a> •
<a href="README.cs.md">🇨🇿 Čeština</a> •
<a href="README.nl.md">🇳🇱 Nederlands</a> •
<a href="README.tr.md">🇹🇷 Türkçe</a> •
<a href="README.uk.md">🇺🇦 Українська</a> •
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="README.id.md">🇮🇩 Indonesia</a> •
<a href="README.th.md">🇹🇭 ไทย</a> •
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
<a href="README.bn.md">🇧🇩 বাংলা</a> •
<a href="README.ur.md">🇵🇰 اردو</a> •
<a href="README.ro.md">🇷🇴 Română</a> •
<a href="README.sv.md">🇸🇪 Svenska</a> •
<a href="README.it.md">🇮🇹 Italiano</a> •
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
<a href="README.hu.md">🇭🇺 Magyar</a> •
<a href="README.fi.md">🇫🇮 Suomi</a> •
<a href="README.da.md">🇩🇰 Dansk</a> •
<a href="README.no.md">🇳🇴 Norsk</a>
</p>
<h4 align="center">Sistema de compressão de memória persistente construído para <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>
<br>
<p align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
</picture>
</a>
</p>
<p align="center">
<a href="#início-rápido">Início Rápido</a> •
<a href="#como-funciona">Como Funciona</a> •
<a href="#ferramentas-de-procura-mcp">Ferramentas de Procura</a> •
<a href="#documentação">Documentação</a> •
<a href="#configuração">Configuração</a> •
<a href="#solução-de-problemas">Solução de Problemas</a> •
<a href="#licença">Licença</a>
</p>
<p align="center">
Claude-Mem preserva o contexto perfeitamente entre sessões, capturando automaticamente observações de uso de ferramentas, gerando resumos semânticos e disponibilizando-os para sessões futuras. Isso permite que Claude mantenha a continuidade do conhecimento sobre projetos mesmo após o término ou reconexão de sessões.
</p>
---
## Início Rápido
Inicie uma nova sessão do Claude Code no terminal e digite os seguintes comandos:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Reinicie o Claude Code. O contexto de sessões anteriores aparecerá automaticamente em novas sessões.
**Principais Recursos:**
- 🧠 **Memória Persistente** - O contexto sobrevive entre sessões
- 📊 **Divulgação Progressiva** - Recuperação de memória em camadas com visibilidade de custo de tokens
- 🔍 **Procura Baseada em Skill** - Consulte seu histórico de projeto com a skill mem-search
- 🖥️ **Interface Web de Visualização** - Fluxo de memória em tempo real em http://localhost:37777
- 💻 **Skill para Claude Desktop** - Busque memória em conversas do Claude Desktop
- 🔒 **Controle de Privacidade** - Use tags `<private>` para excluir conteúdo sensível do armazenamento
- ⚙️ **Configuração de Contexto** - Controle refinado sobre qual contexto é injetado
- 🤖 **Operação Automática** - Nenhuma intervenção manual necessária
- 🔗 **Citações** - Referencie observações passadas com IDs (acesse via http://localhost:37777/api/observation/{id} ou visualize todas no visualizador web em http://localhost:37777)
- 🧪 **Canal Beta** - Experimente recursos experimentais como o Endless Mode através da troca de versões
---
## Documentação
📚 **[Ver Documentação Completa](https://docs.claude-mem.ai/)** - Navegar no site oficial
### Começando
- **[Guia de Instalação](https://docs.claude-mem.ai/installation)** - Início rápido e instalação avançada
- **[Guia de Uso](https://docs.claude-mem.ai/usage/getting-started)** - Como Claude-Mem funciona automaticamente
- **[Ferramentas de Procura](https://docs.claude-mem.ai/usage/search-tools)** - Consulte seu histórico de projeto com linguagem natural
- **[Recursos Beta](https://docs.claude-mem.ai/beta-features)** - Experimente recursos experimentais como o Endless Mode
### Melhores Práticas
- **[Engenharia de Contexto](https://docs.claude-mem.ai/context-engineering)** - Princípios de otimização de contexto para agentes de IA
- **[Divulgação Progressiva](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia por trás da estratégia de preparação de contexto do Claude-Mem
### Arquitetura
- **[Visão Geral](https://docs.claude-mem.ai/architecture/overview)** - Componentes do sistema e fluxo de dados
- **[Evolução da Arquitetura](https://docs.claude-mem.ai/architecture-evolution)** - A jornada da v3 à v5
- **[Arquitetura de Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Como Claude-Mem usa hooks de ciclo de vida
- **[Referência de Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 scripts de hook explicados
- **[Serviço Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP e gerenciamento do Bun
- **[Banco de Dados](https://docs.claude-mem.ai/architecture/database)** - Schema SQLite e Procura FTS5
- **[Arquitetura de Procura](https://docs.claude-mem.ai/architecture/search-architecture)** - Procura híbrida com banco de dados vetorial Chroma
### Configuração e Desenvolvimento
- **[Configuração](https://docs.claude-mem.ai/configuration)** - Variáveis de ambiente e configurações
- **[Desenvolvimento](https://docs.claude-mem.ai/development)** - Build, testes e contribuição
- **[Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** - Problemas comuns e soluções
---
## Como Funciona
**Componentes Principais:**
1. **5 Hooks de Ciclo de Vida** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripts de hook)
2. **Instalação Inteligente** - Verificador de dependências em cache (script pré-hook, não um hook de ciclo de vida)
3. **Serviço Worker** - API HTTP na porta 37777 com interface de visualização web e 10 endpoints de Procura, gerenciado pelo Bun
4. **Banco de Dados SQLite** - Armazena sessões, observações, resumos
5. **Skill mem-search** - Consultas em linguagem natural com divulgação progressiva
6. **Banco de Dados Vetorial Chroma** - Procura híbrida semântica + palavra-chave para recuperação inteligente de contexto
Veja [Visão Geral da Arquitetura](https://docs.claude-mem.ai/architecture/overview) para detalhes.
---
## Skill mem-search
Claude-Mem fornece Procura inteligente através da skill mem-search que se auto-invoca quando você pergunta sobre trabalhos anteriores:
**Como Funciona:**
- Pergunte naturalmente: *"O que fizemos na última sessão?"* ou *"Já corrigimos esse bug antes?"*
- Claude invoca automaticamente a skill mem-search para encontrar contexto relevante
**Operações de Procura Disponíveis:**
1. **Search Observations** - Procura de texto completo em observações
2. **Search Sessions** - Procura de texto completo em resumos de sessão
3. **Search Prompts** - Procura em solicitações brutas do usuário
4. **By Concept** - Encontre por tags de conceito (discovery, problem-solution, pattern, etc.)
5. **By File** - Encontre observações que referenciam arquivos específicos
6. **By Type** - Encontre por tipo (decision, bugfix, feature, refactor, discovery, change)
7. **Recent Context** - Obtenha contexto de sessão recente para um projeto
8. **Timeline** - Obtenha linha do tempo unificada de contexto em torno de um ponto específico no tempo
9. **Timeline by Query** - Busque observações e obtenha contexto de linha do tempo em torno da melhor correspondência
10. **API Help** - Obtenha documentação da API de Procura
**Exemplos de Consultas em Linguagem Natural:**
```
"Quais bugs corrigimos na última sessão?"
"Como implementamos a autenticação?"
"Quais mudanças foram feitas em worker-service.ts?"
"Mostre-me trabalhos recentes neste projeto"
"O que estava acontecendo quando adicionamos a interface de visualização?"
```
Veja [Guia de Ferramentas de Procura](https://docs.claude-mem.ai/usage/search-tools) para exemplos detalhados.
---
## Recursos Beta
Claude-Mem oferece um **canal beta** com recursos experimentais como **Endless Mode** (arquitetura de memória biomimética para sessões estendidas). Alterne entre versões estável e beta pela interface de visualização web em http://localhost:37777 → Settings.
Veja **[Documentação de Recursos Beta](https://docs.claude-mem.ai/beta-features)** para detalhes sobre o Endless Mode e como experimentá-lo.
---
## Requisitos do Sistema
- **Node.js**: 18.0.0 ou superior
- **Claude Code**: Versão mais recente com suporte a plugins
- **Bun**: Runtime JavaScript e gerenciador de processos (instalado automaticamente se ausente)
- **uv**: Gerenciador de pacotes Python para Procura vetorial (instalado automaticamente se ausente)
- **SQLite 3**: Para armazenamento persistente (incluído)
---
## Configuração
As configurações são gerenciadas em `~/.claude-mem/settings.json` (criado automaticamente com valores padrão na primeira execução). Configure modelo de IA, porta do worker, diretório de dados, nível de log e configurações de injeção de contexto.
Veja o **[Guia de Configuração](https://docs.claude-mem.ai/configuration)** para todas as configurações disponíveis e exemplos.
---
## Desenvolvimento
Veja o **[Guia de Desenvolvimento](https://docs.claude-mem.ai/development)** para instruções de build, testes e fluxo de contribuição.
---
## Solução de Problemas
Se você estiver enfrentando problemas, descreva o problema para Claude e a skill troubleshoot diagnosticará automaticamente e fornecerá correções.
Veja o **[Guia de Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** para problemas comuns e soluções.
---
## Relatos de Bug
Crie relatos de bug abrangentes com o gerador automatizado:
```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
```
## Contribuindo
Contribuições são bem-vindas! Por favor:
1. Faça um fork do repositório
2. Crie uma branch de feature
3. Faça suas alterações com testes
4. Atualize a documentação
5. Envie um Pull Request
Veja [Guia de Desenvolvimento](https://docs.claude-mem.ai/development) para o fluxo de contribuição.
---
## Licença
Este projeto está licenciado sob a **GNU Affero General Public License v3.0** (AGPL-3.0).
Copyright (C) 2025 Alex Newman (@thedotmack). Todos os direitos reservados.
Veja o arquivo [LICENSE](LICENSE) para detalhes completos.
**O Que Isso Significa:**
- Você pode usar, modificar e distribuir este software livremente
- Se você modificar e implantar em um servidor de rede, você deve disponibilizar seu código-fonte
- Trabalhos derivados também devem ser licenciados sob AGPL-3.0
- NÃO HÁ GARANTIA para este software
**Nota sobre Ragtime**: O diretório `ragtime/` é licenciado separadamente sob a **PolyForm Noncommercial License 1.0.0**. Veja [ragtime/LICENSE](ragtime/LICENSE) para detalhes.
---
## Suporte
- **Documentação**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositório**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
---
**Construído com Claude Agent SDK** | **Desenvolvido por Claude Code** | **Feito com TypeScript** | **Editado por mig4ng**

88
.agent/services/claude-mem/docs/public/CLAUDE.md Normal file
View File

@@ -0,0 +1,88 @@
# Claude-Mem Public Documentation
## What This Folder Is
This `docs/public/` folder contains the **Mintlify documentation site** - the official user-facing documentation for claude-mem. It's a structured documentation platform with a specific file format and organization.
## Folder Structure
```
docs/
├── public/ ← You are here (Mintlify MDX files)
│ ├── *.mdx - User-facing documentation pages
│ ├── docs.json - Mintlify configuration and navigation
│ ├── architecture/ - Technical architecture docs
│ ├── usage/ - User guides and workflows
│ └── *.webp, *.gif - Assets (logos, screenshots)
└── context/ ← Internal documentation (DO NOT put here)
└── *.md - Planning docs, audits, references
```
## File Requirements
### Mintlify Documentation Files (.mdx)
All official documentation files must be:
- Written in `.mdx` format (Markdown with JSX support)
- Listed in `docs.json` navigation structure
- Follow Mintlify's schema and conventions
The documentation is organized into these sections:
- **Get Started**: Introduction, installation, usage guides
- **Best Practices**: Context engineering, progressive disclosure
- **Configuration & Development**: Settings, dev workflow, troubleshooting
- **Architecture**: System design, components, technical details
### Configuration File
`docs.json` defines:
- Site metadata (name, description, theme)
- Navigation structure
- Branding (logos, colors)
- Footer links and social media
## What Does NOT Belong Here
**Planning documents, design docs, and reference materials go in `/docs/context/` instead:**
Files that belong in `/docs/context/` (NOT here):
- Planning documents (`*-plan.md`, `*-outline.md`)
- Implementation analysis (`*-audit.md`, `*-code-reference.md`)
- Error tracking (`typescript-errors.md`)
- Internal design documents
- PR review responses
- Reference materials (like `agent-sdk-ref.md`)
- Work-in-progress documentation
## How to Add Official Documentation
1. Create a new `.mdx` file in the appropriate subdirectory
2. Add the file path to `docs.json` navigation
3. Use Mintlify's frontmatter and components
4. Follow the existing documentation style
5. Test locally: `npx mintlify dev`
## Development Workflow
**For contributors working on claude-mem:**
- Read `/CLAUDE.md` in the project root for development instructions
- Place planning/design docs in `/docs/context/`
- Only add user-facing documentation to `/docs/public/`
- Test documentation locally with Mintlify CLI before committing
## Testing Documentation
```bash
# Validate docs structure
npx mintlify validate
# Check for broken links
npx mintlify broken-links
# Run local dev server
npx mintlify dev
```
## Summary
**Simple Rule**:
- `/docs/public/` = Official user documentation (Mintlify .mdx files) ← YOU ARE HERE
- `/docs/context/` = Internal docs, plans, references, audits

1225
.agent/services/claude-mem/docs/public/architecture-evolution.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

309
.agent/services/claude-mem/docs/public/architecture/database.mdx Normal file
View File

@@ -0,0 +1,309 @@
---
title: "Database Architecture"
description: "SQLite schema, FTS5 search, and data storage"
---
# Database Architecture
Claude-Mem uses SQLite 3 with the bun:sqlite native module for persistent storage and FTS5 for full-text search.
## Database Location
**Path**: `~/.claude-mem/claude-mem.db`
The database uses SQLite's WAL (Write-Ahead Logging) mode for concurrent reads/writes.
## Database Implementation
**Primary Implementation**: bun:sqlite (native SQLite module)
- Used by: SessionStore and SessionSearch
- Format: Synchronous API with better performance
- **Note**: Database.ts (using bun:sqlite) is legacy code
## Core Tables
### 1. sdk_sessions
Tracks active and completed sessions.
```sql
CREATE TABLE sdk_sessions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
sdk_session_id TEXT UNIQUE NOT NULL,
claude_session_id TEXT,
project TEXT NOT NULL,
prompt_counter INTEGER DEFAULT 0,
status TEXT NOT NULL DEFAULT 'active',
created_at TEXT NOT NULL,
created_at_epoch INTEGER NOT NULL,
completed_at TEXT,
completed_at_epoch INTEGER,
last_activity_at TEXT,
last_activity_epoch INTEGER
);
```
**Indexes**:
- `idx_sdk_sessions_claude_session` on `claude_session_id`
- `idx_sdk_sessions_project` on `project`
- `idx_sdk_sessions_status` on `status`
- `idx_sdk_sessions_created_at` on `created_at_epoch DESC`
### 2. observations
Individual tool executions with hierarchical structure.
```sql
CREATE TABLE observations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
session_id TEXT NOT NULL,
sdk_session_id TEXT NOT NULL,
claude_session_id TEXT,
project TEXT NOT NULL,
prompt_number INTEGER,
tool_name TEXT NOT NULL,
correlation_id TEXT,
-- Hierarchical fields
title TEXT,
subtitle TEXT,
narrative TEXT,
text TEXT,
facts TEXT,
concepts TEXT,
type TEXT,
files_read TEXT,
files_modified TEXT,
created_at TEXT NOT NULL,
created_at_epoch INTEGER NOT NULL,
FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);
```
**Observation Types**:
- `decision` - Architectural or design decisions
- `bugfix` - Bug fixes and corrections
- `feature` - New features or capabilities
- `refactor` - Code refactoring and cleanup
- `discovery` - Learnings about the codebase
- `change` - General changes and modifications
**Indexes**:
- `idx_observations_session` on `session_id`
- `idx_observations_sdk_session` on `sdk_session_id`
- `idx_observations_project` on `project`
- `idx_observations_tool_name` on `tool_name`
- `idx_observations_created_at` on `created_at_epoch DESC`
- `idx_observations_type` on `type`
### 3. session_summaries
AI-generated session summaries (multiple per session).
```sql
CREATE TABLE session_summaries (
id INTEGER PRIMARY KEY AUTOINCREMENT,
sdk_session_id TEXT NOT NULL,
claude_session_id TEXT,
project TEXT NOT NULL,
prompt_number INTEGER,
-- Summary fields
request TEXT,
investigated TEXT,
learned TEXT,
completed TEXT,
next_steps TEXT,
notes TEXT,
created_at TEXT NOT NULL,
created_at_epoch INTEGER NOT NULL,
FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);
```
**Indexes**:
- `idx_session_summaries_sdk_session` on `sdk_session_id`
- `idx_session_summaries_project` on `project`
- `idx_session_summaries_created_at` on `created_at_epoch DESC`
### 4. user_prompts
Raw user prompts with FTS5 search (as of v4.2.0).
```sql
CREATE TABLE user_prompts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
sdk_session_id TEXT NOT NULL,
claude_session_id TEXT,
project TEXT NOT NULL,
prompt_number INTEGER,
prompt_text TEXT NOT NULL,
created_at TEXT NOT NULL,
created_at_epoch INTEGER NOT NULL,
FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);
```
**Indexes**:
- `idx_user_prompts_sdk_session` on `sdk_session_id`
- `idx_user_prompts_project` on `project`
- `idx_user_prompts_created_at` on `created_at_epoch DESC`
### Legacy Tables
- **sessions**: Legacy session tracking (v3.x)
- **memories**: Legacy compressed memory chunks (v3.x)
- **overviews**: Legacy session summaries (v3.x)
## FTS5 Full-Text Search
SQLite FTS5 (Full-Text Search) virtual tables enable fast full-text search across observations, summaries, and user prompts.
### FTS5 Virtual Tables
#### observations_fts
```sql
CREATE VIRTUAL TABLE observations_fts USING fts5(
title,
subtitle,
narrative,
text,
facts,
concepts,
content='observations',
content_rowid='id'
);
```
#### session_summaries_fts
```sql
CREATE VIRTUAL TABLE session_summaries_fts USING fts5(
request,
investigated,
learned,
completed,
next_steps,
notes,
content='session_summaries',
content_rowid='id'
);
```
#### user_prompts_fts
```sql
CREATE VIRTUAL TABLE user_prompts_fts USING fts5(
prompt_text,
content='user_prompts',
content_rowid='id'
);
```
### Automatic Synchronization
FTS5 tables stay in sync via triggers:
```sql
-- Insert trigger example
CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;
-- Update trigger example
CREATE TRIGGER observations_au AFTER UPDATE ON observations BEGIN
INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative, text, facts, concepts)
VALUES('delete', old.id, old.title, old.subtitle, old.narrative, old.text, old.facts, old.concepts);
INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;
-- Delete trigger example
CREATE TRIGGER observations_ad AFTER DELETE ON observations BEGIN
INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative, text, facts, concepts)
VALUES('delete', old.id, old.title, old.subtitle, old.narrative, old.text, old.facts, old.concepts);
END;
```
### FTS5 Query Syntax
FTS5 supports rich query syntax:
- **Simple**: `"error handling"`
- **AND**: `"error" AND "handling"`
- **OR**: `"bug" OR "fix"`
- **NOT**: `"bug" NOT "feature"`
- **Phrase**: `"'exact phrase'"`
- **Column**: `title:"authentication"`
### Security
As of v4.2.3, all FTS5 queries are properly escaped to prevent SQL injection:
- Double quotes are escaped: `query.replace(/"/g, '""')`
- Comprehensive test suite with 332 injection attack tests
## Database Classes
### SessionStore
CRUD operations for sessions, observations, summaries, and user prompts.
**Location**: `src/services/sqlite/SessionStore.ts`
**Methods**:
- `createSession()`
- `getSession()`
- `updateSession()`
- `createObservation()`
- `getObservations()`
- `createSummary()`
- `getSummaries()`
- `createUserPrompt()`
### SessionSearch
FTS5 full-text search with 8 specialized search methods.
**Location**: `src/services/sqlite/SessionSearch.ts`
**Methods**:
- `searchObservations()` - Full-text search across observations
- `searchSessions()` - Full-text search across summaries
- `searchUserPrompts()` - Full-text search across user prompts
- `findByConcept()` - Find by concept tags
- `findByFile()` - Find by file references
- `findByType()` - Find by observation type
- `getRecentContext()` - Get recent session context
- `advancedSearch()` - Combined filters
## Migrations
Database schema is managed via migrations in `src/services/sqlite/migrations.ts`.
**Migration History**:
- Migration 001: Initial schema (sessions, memories, overviews, diagnostics, transcript_events)
- Migration 002: Hierarchical memory fields (title, subtitle, facts, concepts, files_touched)
- Migration 003: SDK sessions and observations
- Migration 004: Session summaries
- Migration 005: Multi-prompt sessions (prompt_counter, prompt_number)
- Migration 006: FTS5 virtual tables and triggers
- Migration 007-010: Various improvements and user prompts table
## Performance Considerations
- **Indexes**: All foreign keys and frequently queried columns are indexed
- **FTS5**: Full-text search is significantly faster than LIKE queries
- **Triggers**: Automatic synchronization has minimal overhead
- **Connection Pooling**: bun:sqlite reuses connections efficiently
- **Synchronous API**: bun:sqlite uses synchronous API for better performance
## Troubleshooting
See [Troubleshooting - Database Issues](../troubleshooting.md#database-issues) for common problems and solutions.

955
.agent/services/claude-mem/docs/public/architecture/hooks.mdx Normal file
View File

@@ -0,0 +1,955 @@
---
title: "Hook Lifecycle"
description: "Complete guide to the 5-stage memory agent lifecycle for platform implementers"
---
# Hook Lifecycle
Claude-Mem implements a **5-stage hook system** that captures development work across Claude Code sessions. This document provides a complete technical reference for developers implementing this pattern on other platforms.
## Architecture Overview
### System Architecture
This two-process architecture works in both Claude Code and VS Code:
```mermaid
graph TB
subgraph EXT["Extension Process (runs in IDE)"]
direction TB
ACT[Extension Activation]
HOOKS[Hook Event Handlers]
ACT --> HOOKS
subgraph HOOK_HANDLERS["5 Lifecycle Hooks"]
H1[SessionStart<br/>activate function]
H2[UserPromptSubmit<br/>command handler]
H3[PostToolUse<br/>middleware]
H4[Stop<br/>idle timeout]
H5[SessionEnd<br/>deactivate function]
end
HOOKS --> HOOK_HANDLERS
end
HOOK_HANDLERS -->|"HTTP<br/>(fire-and-forget<br/>2s timeout)"| HTTP[Worker HTTP API<br/>Port 37777]
subgraph WORKER["Worker Process (separate Node.js)"]
direction TB
HTTP --> API[Express Server]
API --> SESS[Session Manager]
API --> AGENT[SDK Agent]
API --> DB[Database Manager]
AGENT -->|Event-Driven| CLAUDE[Claude Agent SDK]
CLAUDE --> SQLITE[(SQLite + FTS5)]
CLAUDE --> CHROMA[(Chroma Vectors)]
end
style EXT fill:#e1f5ff
style WORKER fill:#fff4e1
style HOOK_HANDLERS fill:#f0f0f0
```
**Key Principles:**
- Extension process never blocks (fire-and-forget HTTP)
- Worker processes observations asynchronously
- Session state persists across IDE restarts
### VS Code Extension API Integration Points
For developers porting to VS Code, here's where to hook into the VS Code Extension API:
```mermaid
graph LR
subgraph VSCODE["VS Code Extension API"]
direction TB
A["activate(context)"]
B["commands.registerCommand()"]
C["chat.createChatParticipant()"]
D["workspace.onDidSaveTextDocument()"]
E["window.onDidChangeActiveTextEditor()"]
F["deactivate()"]
end
subgraph HOOKS["Hook Equivalents"]
direction TB
G[SessionStart]
H[UserPromptSubmit]
I[PostToolUse]
J[Stop/Summary]
K[SessionEnd]
end
subgraph WORKER_API["Worker HTTP Endpoints"]
direction TB
L[GET /api/context/inject]
M[POST /sessions/init]
N[POST /sessions/observations]
O[POST /sessions/summarize]
P[POST /sessions/complete]
end
A --> G
B --> H
C --> H
D --> I
E --> I
F --> K
G --> L
H --> M
I --> N
J --> O
K --> P
style VSCODE fill:#007acc,color:#fff
style HOOKS fill:#f0f0f0
style WORKER_API fill:#4caf50,color:#fff
```
**Implementation Examples:**
```typescript
// VS Code Extension - SessionStart Hook
export async function activate(context: vscode.ExtensionContext) {
const sessionId = generateSessionId()
const project = workspace.name || 'default'
// Fetch context from worker
const response = await fetch(`http://localhost:37777/api/context/inject?project=${project}`)
const context = await response.text()
// Inject into chat or UI panel
injectContextToChat(context)
}
// VS Code Extension - UserPromptSubmit Hook
const command = vscode.commands.registerCommand('extension.command', async (prompt) => {
await fetch('http://localhost:37777/sessions/init', {
method: 'POST',
body: JSON.stringify({ sessionId, project, userPrompt: prompt })
})
})
// VS Code Extension - PostToolUse Hook (middleware pattern)
workspace.onDidSaveTextDocument(async (document) => {
await fetch('http://localhost:37777/api/sessions/observations', {
method: 'POST',
body: JSON.stringify({
claudeSessionId: sessionId,
tool_name: 'FileSave',
tool_input: { path: document.uri.path },
tool_response: 'File saved successfully'
})
})
})
```
### Async Processing Pipeline
How observations flow from extension to database without blocking the IDE:
```mermaid
graph TB
A["Extension: Tool Use Event"] --> B{"Skip List?<br/>(TodoWrite, AskUserQuestion, etc.)"}
B -->|"Skip"| X["Discard"]
B -->|"Keep"| C["Strip Privacy Tags<br/>&lt;private&gt;...&lt;/private&gt;"]
C --> D["HTTP POST to Worker<br/>Port 37777"]
D --> E["2s timeout<br/>fire-and-forget"]
E --> F["Extension continues<br/>(non-blocking)"]
D -.Async Path.-> G["Worker: Queue Observation"]
G --> H["SDK Agent picks up<br/>(event-driven)"]
H --> I["Call Claude API<br/>(compress observation)"]
I --> J["Parse XML response"]
J --> K["Save to SQLite<br/>(sdk_sessions table)"]
K --> L["Sync to Chroma<br/>(vector embeddings)"]
style F fill:#90EE90,stroke:#2d6b2d,stroke-width:3px
style L fill:#87CEEB,stroke:#2d5f8d,stroke-width:3px
style E fill:#ffeb3b,stroke:#c6a700,stroke-width:2px
```
**Critical Pattern:** The extension's HTTP call has a 2-second timeout and doesn't wait for AI processing. The worker handles compression asynchronously using an event-driven queue.
## The 5 Lifecycle Stages
| Stage | Hook | Trigger | Purpose |
|-------|------|---------|---------|
| **1. SessionStart** | `context-hook.js` | User opens Claude Code | Inject prior context silently |
| **2. UserPromptSubmit** | `new-hook.js` | User submits a prompt | Create/get session, save prompt, init worker |
| **3. PostToolUse** | `save-hook.js` | Claude uses any tool | Queue observation for AI compression |
| **4. Stop** | `summary-hook.js` | User stops asking questions | Generate session summary |
| **5. SessionEnd** | `cleanup-hook.js` | Session closes | Mark session completed |
## Hook Configuration
Hooks are configured in `plugin/hooks/hooks.json`:
```json
{
"hooks": {
"SessionStart": [{
"matcher": "startup|clear|compact",
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js",
"timeout": 300
}, {
"type": "command",
"command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs start",
"timeout": 60
}, {
"type": "command",
"command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
"timeout": 60
}]
}],
"UserPromptSubmit": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js",
"timeout": 120
}]
}],
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js",
"timeout": 120
}]
}],
"Stop": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js",
"timeout": 120
}]
}],
"SessionEnd": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js",
"timeout": 120
}]
}]
}
}
```
---
## Stage 1: SessionStart
**Timing**: When user opens Claude Code or resumes session
**Hooks Triggered** (in order):
1. `smart-install.js` - Ensures dependencies are installed
2. `worker-service.cjs start` - Starts the worker service
3. `context-hook.js` - Fetches and silently injects prior session context
<Note>
As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
</Note>
### Sequence Diagram
```mermaid
sequenceDiagram
participant User
participant IDE as IDE/Extension
participant ContextHook as context-hook.js
participant Worker as Worker Service
participant DB as SQLite Database
User->>IDE: Opens workspace / resumes session
IDE->>ContextHook: Trigger SessionStart hook
ContextHook->>ContextHook: Generate/reuse session_id
ContextHook->>Worker: Health check (max 10s retry)
alt Worker Ready
ContextHook->>Worker: GET /api/context/inject?project=X
Worker->>DB: SELECT * FROM observations<br/>WHERE project=X<br/>ORDER BY created_at DESC<br/>LIMIT 50
DB-->>Worker: Last 50 observations
Worker-->>ContextHook: Context markdown
ContextHook-->>IDE: hookSpecificOutput.additionalContext
IDE->>IDE: Inject context to Claude's prompt
IDE-->>User: Session ready with context
else Worker Not Ready
ContextHook-->>IDE: Empty context (graceful degradation)
IDE-->>User: Session ready without context
end
Note over User,DB: Total time: <300ms (with health check)
```
### Context Hook (`context-hook.js`)
**Purpose**: Inject context from previous sessions into Claude's initial context.
**Input** (via stdin):
```json
{
"session_id": "claude-session-123",
"cwd": "/path/to/project",
"source": "startup"
}
```
**Processing**:
1. Wait for worker to be available (health check, max 10 seconds)
2. Call: `GET http://127.0.0.1:37777/api/context/inject?project={project}`
3. Return formatted context as `additionalContext` in `hookSpecificOutput`
**Output** (via stdout):
```json
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "<<formatted context markdown>>"
}
}
```
**Implementation**: `src/hooks/context-hook.ts`
---
## Stage 2: UserPromptSubmit
**Timing**: When user submits any prompt in a session
**Hook**: `new-hook.js`
### Sequence Diagram
```mermaid
sequenceDiagram
participant User
participant IDE as IDE/Extension
participant NewHook as new-hook.js
participant DB as Direct SQLite Access
participant Worker as Worker Service
User->>IDE: Submits prompt: "Add login feature"
IDE->>NewHook: Trigger UserPromptSubmit<br/>{ session_id, cwd, prompt }
NewHook->>NewHook: Extract project = basename(cwd)
NewHook->>NewHook: Strip privacy tags<br/>&lt;private&gt;...&lt;/private&gt;
alt Prompt fully private (empty after stripping)
NewHook-->>IDE: Skip (don't save)
else Prompt has content
NewHook->>DB: INSERT OR IGNORE INTO sdk_sessions<br/>(claude_session_id, project, first_user_prompt)
DB-->>NewHook: sessionDbId (new or existing)
NewHook->>DB: UPDATE sdk_sessions<br/>SET prompt_counter = prompt_counter + 1<br/>WHERE id = sessionDbId
DB-->>NewHook: promptNumber (e.g., 1 for first, 2 for continuation)
NewHook->>DB: INSERT INTO user_prompts<br/>(session_id, prompt_number, prompt)
NewHook->>Worker: POST /sessions/{sessionDbId}/init<br/>{ project, userPrompt, promptNumber }<br/>(fire-and-forget, 2s timeout)
Worker-->>NewHook: 200 OK (or timeout)
NewHook-->>IDE: { continue: true, suppressOutput: true }
IDE-->>User: Prompt accepted
end
Note over NewHook,DB: Idempotent: Same session_id → same sessionDbId
```
**Key Pattern:** The `INSERT OR IGNORE` ensures the same `session_id` always maps to the same `sessionDbId`, enabling conversation continuations.
**Input** (via stdin):
```json
{
"session_id": "claude-session-123",
"cwd": "/path/to/project",
"prompt": "User's actual prompt text"
}
```
**Processing Steps**:
```typescript
// 1. Extract project name from working directory
project = path.basename(cwd)
// 2. Create or get database session (IDEMPOTENT)
sessionDbId = db.createSDKSession(session_id, project, prompt)
// INSERT OR IGNORE: Creates new row if first prompt, returns existing if continuation
// 3. Increment prompt counter
promptNumber = db.incrementPromptCounter(sessionDbId)
// Returns 1 for first prompt, 2 for continuation, etc.
// 4. Strip privacy tags
cleanedPrompt = stripMemoryTagsFromPrompt(prompt)
// Removes <private>...</private> and <claude-mem-context>...</claude-mem-context>
// 5. Skip if fully private
if (!cleanedPrompt || cleanedPrompt.trim() === '') {
return // Don't save, don't call worker
}
// 6. Save user prompt to database
db.saveUserPrompt(session_id, promptNumber, cleanedPrompt)
// 7. Initialize session via worker HTTP
POST http://127.0.0.1:37777/sessions/{sessionDbId}/init
Body: { project, userPrompt, promptNumber }
```
**Output**:
```json
{ "continue": true, "suppressOutput": true }
```
**Implementation**: `src/hooks/new-hook.ts`
<Note>
The same `session_id` flows through ALL hooks in a conversation. The `createSDKSession` call is idempotent - it returns the existing session for continuation prompts.
</Note>
---
## Stage 3: PostToolUse
**Timing**: After Claude uses any tool (Read, Bash, Grep, Write, etc.)
**Hook**: `save-hook.js`
### Sequence Diagram
```mermaid
sequenceDiagram
participant Claude as Claude AI
participant IDE as IDE/Extension
participant SaveHook as save-hook.js
participant Worker as Worker Service
participant Agent as SDK Agent
participant DB as SQLite + Chroma
Claude->>IDE: Uses tool: Read("/src/auth.ts")
IDE->>SaveHook: PostToolUse hook triggered<br/>{ session_id, tool_name, tool_input, tool_response }
SaveHook->>SaveHook: Check skip list<br/>(TodoWrite, AskUserQuestion, etc.)
alt Tool in skip list
SaveHook-->>IDE: Discard (low-value tool)
else Tool allowed
SaveHook->>SaveHook: Strip privacy tags from input/response
SaveHook->>SaveHook: Ensure worker running<br/>(health check)
SaveHook->>Worker: POST /api/sessions/observations<br/>{ claudeSessionId, tool_name, tool_input, tool_response, cwd }<br/>(fire-and-forget, 2s timeout)
SaveHook-->>IDE: { continue: true, suppressOutput: true }
IDE-->>Claude: Tool execution complete
Note over Worker,DB: Async path (doesn't block IDE)
Worker->>Worker: createSDKSession(claudeSessionId)<br/>→ returns sessionDbId
Worker->>Worker: Check if prompt was private<br/>(skip if fully private)
Worker->>Agent: Queue observation for processing
Agent->>Agent: Call Claude SDK to compress<br/>observation into structured format
Agent->>DB: Save compressed observation<br/>to sdk_sessions table
Agent->>DB: Sync to Chroma vector DB
end
Note over SaveHook,DB: Total sync time: ~2ms<br/>AI processing: 1-3s (async)
```
**Key Pattern:** The hook returns immediately after HTTP POST. AI compression happens asynchronously in the worker without blocking Claude's tool execution.
**Input** (via stdin):
```json
{
"session_id": "claude-session-123",
"cwd": "/path/to/project",
"tool_name": "Read",
"tool_input": { "file_path": "/src/index.ts" },
"tool_response": "file contents..."
}
```
**Processing Steps**:
```typescript
// 1. Check blocklist - skip low-value tools
const SKIP_TOOLS = {
'ListMcpResourcesTool', // MCP infrastructure noise
'SlashCommand', // Command invocation
'Skill', // Skill invocation
'TodoWrite', // Task management meta-tool
'AskUserQuestion' // User interaction
}
if (SKIP_TOOLS[tool_name]) return
// 2. Ensure worker is running
await ensureWorkerRunning()
// 3. Send to worker (fire-and-forget HTTP)
POST http://127.0.0.1:37777/api/sessions/observations
Body: {
claudeSessionId: session_id,
tool_name,
tool_input,
tool_response,
cwd
}
Timeout: 2000ms
```
**Worker Processing**:
1. Looks up or creates session: `createSDKSession(claudeSessionId, '', '')`
2. Gets prompt counter
3. Checks privacy (skips if user prompt was entirely private)
4. Strips memory tags from `tool_input` and `tool_response`
5. Queues observation for SDK agent processing
6. SDK agent calls Claude to compress into structured observation
7. Stores observation in database and syncs to Chroma
**Output**:
```json
{ "continue": true, "suppressOutput": true }
```
**Implementation**: `src/hooks/save-hook.ts`
---
## Stage 4: Stop
**Timing**: When user stops or pauses asking questions
**Hook**: `summary-hook.js`
### Sequence Diagram
```mermaid
sequenceDiagram
participant User
participant IDE as IDE/Extension
participant SummaryHook as summary-hook.js
participant Worker as Worker Service
participant Agent as SDK Agent
participant DB as SQLite Database
User->>IDE: Stops asking questions<br/>(pause, idle, or explicit stop)
IDE->>SummaryHook: Stop hook triggered<br/>{ session_id, cwd, transcript_path }
SummaryHook->>SummaryHook: Read transcript JSONL file
SummaryHook->>SummaryHook: Extract last user message<br/>(type: "user")
SummaryHook->>SummaryHook: Extract last assistant message<br/>(type: "assistant", filter &lt;system-reminder&gt;)
SummaryHook->>Worker: POST /api/sessions/summarize<br/>{ claudeSessionId, last_user_message, last_assistant_message }<br/>(fire-and-forget, 2s timeout)
SummaryHook->>Worker: POST /api/processing<br/>{ isProcessing: false }<br/>(stop spinner)
SummaryHook-->>IDE: { continue: true, suppressOutput: true }
IDE-->>User: Session paused/stopped
Note over Worker,DB: Async path
Worker->>Worker: Lookup sessionDbId from claudeSessionId
Worker->>Agent: Queue summarization request
Agent->>Agent: Call Claude SDK with prompt:<br/>"Summarize: request, investigated, learned, completed, next_steps"
Agent->>Agent: Parse XML response
Agent->>DB: INSERT INTO session_summaries<br/>{ session_id, request, investigated, learned, completed, next_steps }
Agent->>DB: Sync to Chroma (for semantic search)
Note over SummaryHook,DB: Total sync time: ~2ms<br/>AI summarization: 2-5s (async)
```
**Key Pattern:** The summary is generated asynchronously and doesn't block the user from resuming work or closing the session.
**Input** (via stdin):
```json
{
"session_id": "claude-session-123",
"cwd": "/path/to/project",
"transcript_path": "/path/to/transcript.jsonl"
}
```
**Processing Steps**:
```typescript
// 1. Extract last messages from transcript JSONL
const lines = fs.readFileSync(transcript_path, 'utf-8').split('\n')
// Find last user message (type: "user")
// Find last assistant message (type: "assistant", filter <system-reminder> tags)
// 2. Ensure worker is running
await ensureWorkerRunning()
// 3. Send summarization request (fire-and-forget HTTP)
POST http://127.0.0.1:37777/api/sessions/summarize
Body: {
claudeSessionId: session_id,
last_user_message: string,
last_assistant_message: string
}
Timeout: 2000ms
// 4. Stop processing spinner
POST http://127.0.0.1:37777/api/processing
Body: { isProcessing: false }
```
**Worker Processing**:
1. Queues summarization for SDK agent
2. Agent calls Claude to generate structured summary
3. Summary stored in database with fields: `request`, `investigated`, `learned`, `completed`, `next_steps`
**Output**:
```json
{ "continue": true, "suppressOutput": true }
```
**Implementation**: `src/hooks/summary-hook.ts`
---
## Stage 5: SessionEnd
**Timing**: When Claude Code session closes (exit, clear, logout, etc.)
**Hook**: `cleanup-hook.js`
### Sequence Diagram
```mermaid
sequenceDiagram
participant User
participant IDE as IDE/Extension
participant CleanupHook as cleanup-hook.js
participant Worker as Worker Service
participant DB as SQLite Database
participant SSE as SSE Clients (Viewer UI)
User->>IDE: Closes session<br/>(exit, clear, logout)
IDE->>CleanupHook: SessionEnd hook triggered<br/>{ session_id, cwd, transcript_path, reason }
CleanupHook->>Worker: POST /api/sessions/complete<br/>{ claudeSessionId, reason }<br/>(fire-and-forget, 2s timeout)
CleanupHook-->>IDE: { continue: true, suppressOutput: true }
IDE-->>User: Session closed
Note over Worker,SSE: Async path
Worker->>Worker: Lookup sessionDbId from claudeSessionId
Worker->>DB: UPDATE sdk_sessions<br/>SET status = 'completed', completed_at = NOW()<br/>WHERE claude_session_id = claudeSessionId
Worker->>SSE: Broadcast session completion event<br/>(for live viewer UI updates)
SSE-->>SSE: Update UI to show session as completed
Note over CleanupHook,SSE: Total sync time: ~2ms
```
**Key Pattern:** Session completion is tracked for analytics and UI updates, but doesn't prevent the user from closing the IDE.
**Input** (via stdin):
```json
{
"session_id": "claude-session-123",
"cwd": "/path/to/project",
"transcript_path": "/path/to/transcript.jsonl",
"reason": "exit"
}
```
**Processing Steps**:
```typescript
// Send session complete (fire-and-forget HTTP)
POST http://127.0.0.1:37777/api/sessions/complete
Body: {
claudeSessionId: session_id,
reason: string // 'exit' | 'clear' | 'logout' | 'prompt_input_exit' | 'other'
}
Timeout: 2000ms
```
**Worker Processing**:
1. Finds session by `claudeSessionId`
2. Marks session as 'completed' in database
3. Broadcasts session completion event to SSE clients
**Output**:
```json
{ "continue": true, "suppressOutput": true }
```
**Implementation**: `src/hooks/cleanup-hook.ts`
---
## Session State Machine
Understanding session lifecycle and state transitions:
```mermaid
stateDiagram-v2
[*] --> Initialized: SessionStart hook<br/>(generate session_id)
Initialized --> Active: UserPromptSubmit<br/>(first prompt)
Active --> Active: UserPromptSubmit<br/>(continuation prompts)<br/>promptNumber++
Active --> ObservationQueued: PostToolUse hook<br/>(tool execution captured)
ObservationQueued --> Active: Observation processed<br/>(async, non-blocking)
Active --> Summarizing: Stop hook<br/>(user pauses/stops)
Summarizing --> Active: User resumes<br/>(new prompt submitted)
Summarizing --> Completed: SessionEnd hook<br/>(session closes)
Active --> Completed: SessionEnd hook<br/>(session closes)
Completed --> [*]
note right of Active
session_id: constant (e.g., "claude-session-abc123")
sessionDbId: constant (e.g., 42)
promptNumber: increments (1, 2, 3, ...)
All operations use same sessionDbId
end note
note right of ObservationQueued
Fire-and-forget HTTP
AI compression happens async
IDE never blocks
end note
```
**Key Insights:**
- `session_id` never changes during a conversation
- `sessionDbId` is the database primary key for the session
- `promptNumber` increments with each user prompt
- State transitions are non-blocking (fire-and-forget pattern)
---
## Database Schema
The session-centric data model that enables cross-session memory:
```mermaid
erDiagram
SDK_SESSIONS ||--o{ USER_PROMPTS : "has many"
SDK_SESSIONS ||--o{ OBSERVATIONS : "has many"
SDK_SESSIONS ||--o{ SESSION_SUMMARIES : "has many"
SDK_SESSIONS {
integer id PK "Auto-increment primary key"
text claude_session_id UK "From IDE (e.g., 'claude-session-123')"
text project "Project name from cwd basename"
text first_user_prompt "Initial prompt that started session"
integer prompt_counter "Increments with each UserPromptSubmit"
text status "initialized | active | completed"
datetime created_at
datetime completed_at
}
USER_PROMPTS {
integer id PK
integer session_id FK "References SDK_SESSIONS.id"
integer prompt_number "1, 2, 3, ... matches prompt_counter"
text prompt "User's actual prompt (tags stripped)"
datetime created_at
}
OBSERVATIONS {
integer id PK
integer session_id FK "References SDK_SESSIONS.id"
integer prompt_number "Which prompt this observation belongs to"
text tool_name "Read, Bash, Grep, Write, etc."
text tool_input_json "Stripped of privacy tags"
text tool_response_text "Stripped of privacy tags"
text compressed_observation "AI-generated structured observation"
datetime created_at
}
SESSION_SUMMARIES {
integer id PK
integer session_id FK "References SDK_SESSIONS.id"
text request "What user requested"
text investigated "What was explored"
text learned "What was discovered"
text completed "What was accomplished"
text next_steps "What remains to be done"
datetime created_at
}
```
**Idempotency Pattern:**
```sql
-- This ensures same session_id always maps to same sessionDbId
INSERT OR IGNORE INTO sdk_sessions (claude_session_id, project, first_user_prompt)
VALUES (?, ?, ?)
RETURNING id;
-- If already exists, returns existing row
-- If new, creates and returns new row
```
**Foreign Key Cascade:**
All child tables (user_prompts, observations, session_summaries) use `session_id` foreign key referencing `SDK_SESSIONS.id`. This ensures:
- All data for a session is queryable by sessionDbId
- Session deletions cascade to child tables
- Efficient joins for context injection
<Warning>
Never generate your own session IDs. Always use the `session_id` provided by the IDE - this is the source of truth for linking all data together.
</Warning>
---
## Privacy & Tag Stripping
### Dual-Tag System
```typescript
// User-Level Privacy Control (manual)
<private>sensitive data</private>
// System-Level Recursion Prevention (auto-injected)
<claude-mem-context>...</claude-mem-context>
```
### Processing Pipeline
**Location**: `src/utils/tag-stripping.ts`
```typescript
// Called by: new-hook.js (user prompts)
stripMemoryTagsFromPrompt(prompt: string): string
// Called by: save-hook.js (tool_input, tool_response)
stripMemoryTagsFromJson(jsonString: string): string
```
**Execution Order** (Edge Processing):
1. `new-hook.js` strips tags from user prompt before saving
2. `save-hook.js` strips tags from tool data before sending to worker
3. Worker strips tags again (defense in depth) before storing
---
## SDK Agent Processing
### Query Loop (Event-Driven)
**Location**: `src/services/worker/SDKAgent.ts`
```typescript
async startSession(session: ActiveSession, worker?: any) {
// 1. Create event-driven message generator
const messageGenerator = this.createMessageGenerator(session)
// 2. Run Agent SDK query loop
const queryResult = query({
prompt: messageGenerator,
options: {
model: 'claude-sonnet-4-5',
disallowedTools: ['Bash', 'Read', 'Write', ...], // Observer-only
abortController: session.abortController
}
})
// 3. Process responses
for await (const message of queryResult) {
if (message.type === 'assistant') {
await this.processSDKResponse(session, text, worker)
}
}
}
```
### Message Types
The message generator yields three types of prompts:
1. **Initial Prompt** (prompt #1): Full instructions for starting observation
2. **Continuation Prompt** (prompt #2+): Context-only for continuing work
3. **Observation Prompts**: Tool use data to compress into observations
4. **Summary Prompts**: Session data to summarize
---
## Implementation Checklist
For developers implementing this pattern on other platforms:
### Hook Registration
- [ ] Define hook entry points in platform config
- [ ] 5 hook types: SessionStart (2 hooks), UserPromptSubmit, PostToolUse, Stop, SessionEnd
- [ ] Pass `session_id`, `cwd`, and context-specific data
### Database Schema
- [ ] SQLite with WAL mode
- [ ] 4 main tables: `sdk_sessions`, `user_prompts`, `observations`, `session_summaries`
- [ ] Indices for common queries
### Worker Service
- [ ] HTTP server on configurable port (default 37777)
- [ ] Bun runtime for process management
- [ ] 3 core services: SessionManager, SDKAgent, DatabaseManager
### Hook Implementation
- [ ] context-hook: `GET /api/context/inject` (with health check)
- [ ] new-hook: createSDKSession, saveUserPrompt, `POST /sessions/{id}/init`
- [ ] save-hook: Skip low-value tools, `POST /api/sessions/observations`
- [ ] summary-hook: Parse transcript, `POST /api/sessions/summarize`
- [ ] cleanup-hook: `POST /api/sessions/complete`
### Privacy & Tags
- [ ] Implement `stripMemoryTagsFromPrompt()` and `stripMemoryTagsFromJson()`
- [ ] Process tags at hook layer (edge processing)
- [ ] Max tag count = 100 (ReDoS protection)
### SDK Integration
- [ ] Call Claude Agent SDK to process observations/summaries
- [ ] Parse XML responses for structured data
- [ ] Store to database + sync to vector DB
---
## Key Design Principles
1. **Session ID is Source of Truth**: Never generate your own session IDs
2. **Idempotent Database Operations**: Use `INSERT OR IGNORE` for session creation
3. **Edge Processing for Privacy**: Strip tags at hook layer before data reaches worker
4. **Fire-and-Forget for Non-Blocking**: HTTP timeouts prevent IDE blocking
5. **Event-Driven, Not Polling**: Zero-latency queue notification to SDK agent
6. **Everything Saves Always**: No "orphaned" sessions
---
## Common Pitfalls
| Problem | Root Cause | Solution |
|---------|-----------|----------|
| Session ID mismatch | Different `session_id` used in different hooks | Always use ID from hook input |
| Duplicate sessions | Creating new session instead of using existing | Use `INSERT OR IGNORE` with `session_id` as key |
| Blocking IDE | Waiting for full response | Use fire-and-forget with short timeouts |
| Memory tags in DB | Stripping tags in wrong layer | Strip at hook layer, before HTTP send |
| Worker not found | Health check too fast | Add retry loop with exponential backoff |
---
## Related Documentation
- [Worker Service](/architecture/worker-service) - HTTP API and async processing
- [Database Schema](/architecture/database) - SQLite tables and FTS5 search
- [Privacy Tags](/usage/private-tags) - Using `<private>` tags
- [Troubleshooting](/troubleshooting) - Common hook issues

240
.agent/services/claude-mem/docs/public/architecture/overview.mdx Normal file
View File

@@ -0,0 +1,240 @@
---
title: "Architecture Overview"
description: "System components and data flow in Claude-Mem"
---
# Architecture Overview
## System Components
Claude-Mem operates as a Claude Code plugin with five core components:
1. **Plugin Hooks** - Capture lifecycle events (6 hook files)
2. **Smart Install** - Cached dependency checker (pre-hook script, runs before context-hook)
3. **Worker Service** - Process observations via Claude Agent SDK + HTTP API (10 search endpoints)
4. **Database Layer** - Store sessions and observations (SQLite + FTS5 + ChromaDB)
5. **mem-search Skill** - Skill-based search with progressive disclosure (v5.4.0+)
6. **Viewer UI** - Web-based real-time memory stream visualization
## Technology Stack
| Layer | Technology |
|------------------------|-------------------------------------------|
| **Language** | TypeScript (ES2022, ESNext modules) |
| **Runtime** | Node.js 18+ |
| **Database** | SQLite 3 with bun:sqlite driver |
| **Vector Store** | ChromaDB (optional, for semantic search) |
| **HTTP Server** | Express.js 4.18 |
| **Real-time** | Server-Sent Events (SSE) |
| **UI Framework** | React + TypeScript |
| **AI SDK** | @anthropic-ai/claude-agent-sdk |
| **Build Tool** | esbuild (bundles TypeScript) |
| **Process Manager** | Bun |
| **Testing** | Node.js built-in test runner |
## Data Flow
### Memory Pipeline
```
Hook (stdin) → Database → Worker Service → SDK Processor → Database → Next Session Hook
```
1. **Input**: Claude Code sends tool execution data via stdin to hooks
2. **Storage**: Hooks write observations to SQLite database
3. **Processing**: Worker service reads observations, processes via SDK
4. **Output**: Processed summaries written back to database
5. **Retrieval**: Next session's context hook reads summaries from database
### Search Pipeline
```
User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
```
1. **User Query**: User asks naturally: "What bugs did we fix?"
2. **MCP Tools Invoked**: Claude recognizes intent and invokes MCP search tools
3. **HTTP API**: MCP tools call HTTP endpoint (e.g., `/api/search/observations`)
4. **SessionSearch**: Worker service queries FTS5 virtual tables
5. **Format**: Results formatted and returned via MCP
6. **Return**: Claude presents formatted results to user
Uses 3-layer progressive disclosure: search → timeline → get_observations
## Session Lifecycle
```
┌─────────────────────────────────────────────────────────────────┐
│ 0. Smart Install Pre-Hook Fires │
│ Checks dependencies (cached), only runs on version changes │
│ Not a lifecycle hook - runs before context-hook starts │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Context Hook Fires │
│ Starts Bun worker if needed, injects context from previous │
│ sessions (configurable observation count) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. User Types Prompt → UserPromptSubmit Hook Fires │
│ Creates session in database, saves raw user prompt for FTS5 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. Claude Uses Tools → PostToolUse Hook Fires (100+ times) │
│ Captures tool executions, sends to worker for AI compression │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. Worker Processes → Claude Agent SDK Analyzes │
│ Extracts structured learnings via iterative AI processing │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 5. Claude Stops → Summary Hook Fires │
│ Generates final summary with request, completions, learnings │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 6. Session Ends → Cleanup Hook Fires │
│ Marks session complete (graceful, not DELETE), ready for │
│ next session context. Skips on /clear to preserve ongoing │
└─────────────────────────────────────────────────────────────────┘
```
## Directory Structure
```
claude-mem/
├── src/
│ ├── hooks/ # Hook implementations (6 hooks)
│ │ ├── context-hook.ts # SessionStart
│ │ ├── user-message-hook.ts # UserMessage (for debugging)
│ │ ├── new-hook.ts # UserPromptSubmit
│ │ ├── save-hook.ts # PostToolUse
│ │ ├── summary-hook.ts # Stop
│ │ ├── cleanup-hook.ts # SessionEnd
│ │ └── hook-response.ts # Hook response utilities
│ │
│ ├── sdk/ # Claude Agent SDK integration
│ │ ├── prompts.ts # XML prompt builders
│ │ ├── parser.ts # XML response parser
│ │ └── worker.ts # Main SDK agent loop
│ │
│ ├── services/
│ │ ├── worker-service.ts # Express HTTP + SSE service
│ │ └── sqlite/ # Database layer
│ │ ├── SessionStore.ts # CRUD operations
│ │ ├── SessionSearch.ts # FTS5 search service
│ │ ├── migrations.ts
│ │ └── types.ts
│ │
│ ├── ui/ # Viewer UI
│ │ └── viewer/ # React + TypeScript web interface
│ │ ├── components/ # UI components
│ │ ├── hooks/ # React hooks
│ │ ├── utils/ # Utilities
│ │ └── assets/ # Fonts, logos
│ │
│ ├── shared/ # Shared utilities
│ │ ├── config.ts
│ │ ├── paths.ts
│ │ └── storage.ts
│ │
│ └── utils/
│ ├── logger.ts
│ ├── platform.ts
│ └── port-allocator.ts
│
├── scripts/ # Build and utility scripts
│ └── smart-install.js # Cached dependency checker (pre-hook)
│
├── plugin/ # Plugin distribution
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── hooks/
│ │ └── hooks.json
│ ├── scripts/ # Built executables
│ │ ├── context-hook.js
│ │ ├── user-message-hook.js
│ │ ├── new-hook.js
│ │ ├── save-hook.js
│ │ ├── summary-hook.js
│ │ ├── cleanup-hook.js
│ │ └── worker-service.cjs # Background worker + HTTP API
│ │
│ ├── skills/ # Agent skills (v5.4.0+)
│ │ ├── mem-search/ # Search skill with progressive disclosure (v5.5.0)
│ │ │ ├── SKILL.md # Skill frontmatter (~250 tokens)
│ │ │ ├── operations/ # 12 detailed operation docs
│ │ │ └── principles/ # 2 principle guides
│ │ ├── troubleshoot/ # Troubleshooting skill
│ │ │ ├── SKILL.md
│ │ │ └── operations/ # 6 operation docs
│ │ └── version-bump/ # Version management skill (deprecated)
│ │
│ └── ui/ # Built viewer UI
│ └── viewer.html # Self-contained bundle
│
├── tests/ # Test suite
├── docs/ # Documentation
└── ecosystem.config.cjs # Process configuration (deprecated)
```
## Component Details
### 1. Plugin Hooks (6 Hooks)
- **context-hook.js** - SessionStart: Starts Bun worker, injects context
- **user-message-hook.js** - UserMessage: Debugging hook
- **new-hook.js** - UserPromptSubmit: Creates session, saves prompt
- **save-hook.js** - PostToolUse: Captures tool executions
- **summary-hook.js** - Stop: Generates session summary
- **cleanup-hook.js** - SessionEnd: Marks session complete
**Note**: smart-install.js is a pre-hook dependency checker (not a lifecycle hook). It's called before context-hook via command chaining in hooks.json and only runs when dependencies need updating.
See [Plugin Hooks](/architecture/hooks) for detailed hook documentation.
### 2. Worker Service
Express.js HTTP server on port 37777 (configurable) with:
- 10 search HTTP API endpoints (v5.4.0+)
- 8 viewer UI HTTP/SSE endpoints
- Async observation processing via Claude Agent SDK
- Real-time updates via Server-Sent Events
- Auto-managed by Bun
See [Worker Service](/architecture/worker-service) for HTTP API and endpoints.
### 3. Database Layer
SQLite3 with bun:sqlite driver featuring:
- FTS5 virtual tables for full-text search
- SessionStore for CRUD operations
- SessionSearch for FTS5 queries
- Location: `~/.claude-mem/claude-mem.db`
See [Database Architecture](/architecture/database) for schema and FTS5 search.
### 4. mem-search Skill (v5.4.0+)
Skill-based search with progressive disclosure providing 10 search operations:
- Search observations, sessions, prompts (full-text FTS5)
- Filter by type, concept, file
- Get recent context, timeline, timeline by query
- API help documentation
**Token Savings**: ~2,250 tokens per session vs MCP approach
- Skill frontmatter: ~250 tokens (loaded at session start)
- Full instructions: ~2,500 tokens (loaded on-demand when invoked)
- HTTP API endpoints instead of MCP tools
**Skill Enhancement (v5.5.0)**: Renamed from "search" to "mem-search" for better scope differentiation. Effectiveness increased from 67% to 100% with enhanced triggers and comprehensive documentation.
See [Search Architecture](/architecture/search-architecture) for technical details and examples.
### 5. Viewer UI
React + TypeScript web interface at http://localhost:37777 featuring:
- Real-time memory stream via Server-Sent Events
- Infinite scroll pagination with automatic deduplication
- Project filtering and settings persistence
- GPU-accelerated animations
- Self-contained HTML bundle (viewer.html)
Built with esbuild into a single file deployment.

559
.agent/services/claude-mem/docs/public/architecture/pm2-to-bun-migration.mdx Normal file
View File

@@ -0,0 +1,559 @@
---
title: "PM2 to Bun Migration"
description: "Complete technical documentation for the process management and database driver migration in v7.1.0"
---
<Note>
**Historical Migration Documentation**
This document describes the PM2 to Bun migration that occurred in v7.1.0 (December 2025). If you're installing claude-mem for the first time, this migration has already been completed and you can use the current Bun-based system documented in the main guides.
This documentation is preserved for users upgrading from versions older than v7.1.0.
</Note>
# PM2 to Bun Migration: Complete Technical Documentation
**Version**: 7.1.0
**Date**: December 2025
**Migration Type**: Process Management (PM2 → Bun) + Database Driver (better-sqlite3 → bun:sqlite)
## Executive Summary
Claude-mem version 7.1.0 introduces two major architectural migrations:
1. **Process Management**: PM2 → Custom Bun-based ProcessManager
2. **Database Driver**: better-sqlite3 npm package → bun:sqlite runtime module
Both migrations are **automatic** and **transparent** to end users. The first time a hook fires after updating to 7.1.0+, the system performs a one-time cleanup of legacy PM2 processes and transitions to the new architecture.
### Key Benefits
- **Simplified Dependencies**: Removes PM2 and better-sqlite3 npm packages
- **Improved Cross-Platform Support**: Better Windows compatibility
- **Faster Installation**: No native module compilation required
- **Built-in Runtime**: Leverages Bun's built-in process management and SQLite
- **Reduced Complexity**: Custom ProcessManager is simpler than PM2 integration
### Migration Impact
- **Data Preservation**: User data, settings, and database remain unchanged
- **Automatic Cleanup**: Old PM2 processes automatically terminated (all platforms)
- **No User Action Required**: Migration happens automatically on first hook trigger
- **Backward Compatible**: SQLite database format unchanged (only driver changed)
## Architecture Comparison
### Old System (PM2-based)
<AccordionGroup>
<Accordion title="Process Management (PM2)">
**Component**: PM2 (Process Manager 2)
- **Package**: `pm2` npm dependency
- **Process Name**: `claude-mem-worker`
- **Management**: External PM2 daemon manages lifecycle
- **Discovery**: `pm2 list`, `pm2 describe` commands
- **Auto-restart**: PM2 automatically restarts on crash
- **Logs**: `~/.pm2/logs/claude-mem-worker-*.log`
- **PID File**: `~/.pm2/pids/claude-mem-worker.pid`
**Lifecycle Commands**:
```bash
pm2 start <script> # Start worker
pm2 stop claude-mem-worker # Stop worker
pm2 restart claude-mem-worker # Restart worker
pm2 delete claude-mem-worker # Remove from PM2
pm2 logs claude-mem-worker # View logs
```
**Pain Points**:
- Additional npm dependency required
- PM2 daemon must be running
- Potential conflicts with other PM2 processes
- Windows compatibility issues
- Complex configuration for simple use case
</Accordion>
<Accordion title="Database Driver (better-sqlite3)">
**Component**: better-sqlite3
- **Package**: `better-sqlite3` npm package (native module)
- **Installation**: Requires native compilation (node-gyp)
- **Windows**: Requires Visual Studio build tools + Python
- **Import**: `import Database from 'better-sqlite3'`
**Installation Requirements**:
- Node.js development headers
- C++ compiler (gcc/clang on Mac/Linux, MSVC on Windows)
- Python (for node-gyp)
- Windows: Visual Studio Build Tools
</Accordion>
</AccordionGroup>
### New System (Bun-based)
<AccordionGroup>
<Accordion title="Process Management (Custom ProcessManager)">
**Component**: Custom ProcessManager (`src/services/process/ProcessManager.ts`)
- **Package**: Built-in Bun APIs (no external dependency)
- **Process Spawn**: `Bun.spawn()` with detached mode
- **Management**: Direct process control via PID file
- **Discovery**: PID file + process existence check + HTTP health check
- **Auto-restart**: Hook-triggered restart on failure detection
- **Logs**: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
- **PID File**: `~/.claude-mem/.worker.pid`
- **Port File**: `~/.claude-mem/.worker.port` (new)
**Lifecycle Commands**:
```bash
npm run worker:start # Start worker
npm run worker:stop # Stop worker
npm run worker:restart # Restart worker
npm run worker:status # Check status
npm run worker:logs # View logs
```
**Core Mechanisms**:
1. **PID File Management**:
- File: `~/.claude-mem/.worker.pid`
- Content: Process ID (e.g., "35557")
- Validation: Process existence via `kill(pid, 0)` signal
2. **Port File Management**:
- File: `~/.claude-mem/.worker.port`
- Content: Two lines (port number, PID)
- Purpose: Track port binding and validate PID match
3. **Health Checking**:
- Layer 1: PID file exists?
- Layer 2: Process alive? (`kill(pid, 0)`)
- Layer 3: HTTP health check (`GET /health`)
- All three must pass for "healthy" status
**Advantages**:
- No external dependencies
- Simpler codebase (direct control)
- Better error handling and validation
- Platform-agnostic (Bun handles platform differences)
</Accordion>
<Accordion title="Database Driver (bun:sqlite)">
**Component**: bun:sqlite
- **Package**: Built into Bun runtime (no npm package)
- **Installation**: None required (comes with Bun ≥1.0)
- **Platform**: Works anywhere Bun works
- **Import**: `import { Database } from 'bun:sqlite'`
- **API**: Similar to better-sqlite3 (synchronous)
**Installation Requirements**:
- Bun ≥1.0 (automatically installed if missing)
- No native compilation required
- No platform-specific build tools needed
**Compatibility**:
- SQLite database format: **Unchanged**
- Database file: `~/.claude-mem/claude-mem.db` (same location)
- Query syntax: **Identical** (both use SQLite SQL)
</Accordion>
</AccordionGroup>
## Migration Mechanics
### One-Time PM2 Cleanup
The migration system uses a marker-based approach to perform PM2 cleanup exactly once.
**Implementation**: `src/shared/worker-utils.ts:73-86`
```typescript
// Clean up legacy PM2 (one-time migration)
const pm2MigratedMarker = join(DATA_DIR, '.pm2-migrated');
if (!existsSync(pm2MigratedMarker)) {
try {
spawnSync('pm2', ['delete', 'claude-mem-worker'], { stdio: 'ignore' });
// Mark migration as complete
writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
logger.debug('SYSTEM', 'PM2 cleanup completed and marked');
} catch {
// PM2 not installed or process doesn't exist - still mark as migrated
writeFileSync(pm2MigratedMarker, new Date().toISOString(), 'utf-8');
}
}
```
### Migration Trigger Points
<Steps>
<Step title="Hook Execution">
SessionStart, UserPromptSubmit, or PostToolUse hooks execute using new 7.1.0 code
</Step>
<Step title="Worker Status Check">
`ensureWorkerRunning()` checks if `~/.claude-mem/.worker.pid` exists (it doesn't for first run after update)
</Step>
<Step title="Start Worker Decision">
Worker not running → Call `startWorker()`
</Step>
<Step title="Migration Check">
Check if `~/.claude-mem/.pm2-migrated` exists
</Step>
<Step title="PM2 Cleanup">
Execute `pm2 delete claude-mem-worker` (errors ignored), create marker file
</Step>
<Step title="New Worker Start">
Spawn new Bun-managed worker process with PID and port files
</Step>
</Steps>
### Marker File
**Location**: `~/.claude-mem/.pm2-migrated`
**Content**: ISO 8601 timestamp
```
2025-12-13T00:18:39.673Z
```
**Purpose**:
- One-time migration flag
- Prevents repeated PM2 cleanup on every start
- Persists across restarts and reboots
**Lifecycle**:
- Created: First hook trigger after update to 7.1.0+ (all platforms)
- Updated: Never
- Deleted: Never (user could manually delete to force re-migration)
## User Experience Timeline
### First Session After Update
<Note>
This is the critical migration moment. The process takes approximately 2-5 seconds.
</Note>
**Step-by-Step Execution**:
1. **Hook fires** (SessionStart most common)
2. **Worker status check**: No PID file → worker not running
3. **Migration check**: No marker file → run PM2 cleanup
4. **PM2 cleanup**: `pm2 delete claude-mem-worker` (old worker terminated)
5. **Marker creation**: `~/.claude-mem/.pm2-migrated` with timestamp
6. **New worker start**: Bun process spawned, PID/port files created
7. **Verification**: Process check + HTTP health check
8. **Hook completes**: Claude Code session starts normally
**User Observable Behavior**:
- Slight delay on first startup (PM2 cleanup + new worker spawn)
- No error messages (cleanup failures silently handled)
- Worker appears running via `npm run worker:status`
- Old PM2 worker no longer in `pm2 list`
### Subsequent Sessions
After migration completes, every hook trigger follows the fast path:
1. PID file exists? **YES**
2. Process alive? **YES**
3. HTTP health check? **SUCCESS**
4. Result: Worker already running, done (~50ms)
No migration logic runs on subsequent sessions.
## Platform-Specific Behavior
### Platform Comparison
| Feature | macOS | Linux | Windows |
|---------|-------|-------|---------|
| PM2 Cleanup | Attempted | Attempted | Attempted |
| Marker File | Created | Created | Created |
| Process Signals | POSIX (native) | POSIX (native) | Bun abstraction |
| Bun Support | Full | Full | Full |
| PID File | Yes | Yes | Yes |
| Port File | Yes | Yes | Yes |
| Health Check | HTTP | HTTP | HTTP |
| Migration Delay | ~2-5s first time | ~2-5s first time | ~2-5s first time |
### Platform Notes
<Tabs>
<Tab title="macOS">
- POSIX signal handling works natively
- Bun fully supported
- No platform-specific workarounds needed
</Tab>
<Tab title="Linux">
- Identical behavior to macOS
- POSIX signal handling
- Works on Ubuntu, Debian, RHEL, CentOS, Arch
- Alpine may require glibc (not musl)
</Tab>
<Tab title="Windows">
- PM2 cleanup now runs (safe due to try/catch)
- Bun abstracts signal handling differences
- Path module handles Windows separators
- File locking handled by SQLite
</Tab>
</Tabs>
## Observable Changes
### Command Changes
| Old (PM2) | New (Bun) | Notes |
|-----------|-----------|-------|
| `pm2 list` | `npm run worker:status` | Shows worker status |
| `pm2 start <script>` | `npm run worker:start` | Start worker |
| `pm2 stop claude-mem-worker` | `npm run worker:stop` | Stop worker |
| `pm2 restart claude-mem-worker` | `npm run worker:restart` | Restart worker |
| `pm2 delete claude-mem-worker` | `npm run worker:stop` | Remove worker |
| `pm2 logs claude-mem-worker` | `npm run worker:logs` | View logs |
| `pm2 describe claude-mem-worker` | `npm run worker:status` | Detailed status |
| `pm2 monit` | No equivalent | PM2-specific monitoring |
### File Location Changes
**Logs**:
```
Old: ~/.pm2/logs/claude-mem-worker-out.log
~/.pm2/logs/claude-mem-worker-error.log
New: ~/.claude-mem/logs/worker-YYYY-MM-DD.log
```
**PID Files**:
```
Old: ~/.pm2/pids/claude-mem-worker.pid
New: ~/.claude-mem/.worker.pid
```
**Process State**:
```
Old: PM2 daemon memory (pm2 save)
New: ~/.claude-mem/.worker.pid
~/.claude-mem/.worker.port
~/.claude-mem/.pm2-migrated (all platforms)
```
**Database** (unchanged):
```
Same: ~/.claude-mem/claude-mem.db
```
### User-Visible Changes
**Before Update**:
```bash
$ pm2 list
┌────┬────────────────────┬─────────┬─────────┬──────────┐
│ id │ name │ status │ restart │ uptime │
├────┼────────────────────┼─────────┼─────────┼──────────┤
│ 0 │ claude-mem-worker │ online │ 0 │ 2d 5h │
└────┴────────────────────┴─────────┴─────────┴──────────┘
```
**After Update**:
```bash
$ pm2 list
# Empty - worker no longer managed by PM2
$ npm run worker:status
Worker is running
PID: 35557
Port: 37777
Uptime: 2h 15m
```
### Orphaned Files
After migration, these PM2 files may remain (safe to delete):
```
~/.pm2/ # Entire PM2 directory
~/.pm2/logs/ # Old logs
~/.pm2/pids/ # Old PID files
~/.pm2/pm2.log # PM2 daemon log
~/.pm2/dump.pm2 # PM2 process dump
```
**Cleanup (optional)**:
```bash
# Remove PM2 entirely (if not used for other processes)
pm2 kill
rm -rf ~/.pm2
# Or just remove claude-mem logs
rm -f ~/.pm2/logs/claude-mem-worker-*.log
rm -f ~/.pm2/pids/claude-mem-worker.pid
```
## File System State
### State Directory Structure
**Before Migration** (PM2 system):
```
~/.claude-mem/
├── claude-mem.db # Database (unchanged)
├── chroma/ # Vector embeddings (unchanged)
├── logs/ # Application logs (unchanged)
└── settings.json # User settings (unchanged)
~/.pm2/
├── logs/
│ ├── claude-mem-worker-out.log
│ └── claude-mem-worker-error.log
├── pids/
│ └── claude-mem-worker.pid
└── pm2.log
```
**After Migration** (Bun system):
```
~/.claude-mem/
├── claude-mem.db # Database (same file)
├── chroma/ # Vector embeddings (unchanged)
├── logs/
│ └── worker-2025-12-13.log # New log format
├── settings.json # User settings (unchanged)
├── .worker.pid # NEW: Process ID
├── .worker.port # NEW: Port + PID
└── .pm2-migrated # NEW: Migration marker (all platforms)
~/.pm2/ # Orphaned (safe to delete)
├── logs/ # Old logs (no longer written)
├── pids/ # Old PID (no longer updated)
└── pm2.log # PM2 daemon log (not used)
```
## Edge Cases and Troubleshooting
### Scenario 1: Migration Fails (PM2 Still Running)
<Warning>
This is rare but can happen if PM2 has watch mode enabled or the process is manually restarted.
</Warning>
**Symptoms**:
- `pm2 list` still shows `claude-mem-worker`
- Port conflict errors in logs
- Worker fails to start
**Resolution**:
```bash
# Manual cleanup
pm2 delete claude-mem-worker
pm2 save # Persist the deletion
# Force re-migration (optional)
rm ~/.claude-mem/.pm2-migrated
# Restart worker
npm run worker:restart
```
### Scenario 2: Stale PID File (Process Dead)
**Symptoms**:
- `npm run worker:status` shows "not running"
- `.worker.pid` file exists
- Process ID doesn't exist
**Automatic Recovery**: Next hook trigger detects dead process and starts a fresh worker.
**Manual Resolution**:
```bash
rm ~/.claude-mem/.worker.pid
rm ~/.claude-mem/.worker.port
npm run worker:start
```
### Scenario 3: Port Already in Use
**Error**: `EADDRINUSE: address already in use`
**Resolution**:
```bash
# Check what's using the port
lsof -i :37777
# Kill the process
kill -9 <PID>
# Restart worker
npm run worker:restart
```
### Common Error Messages
| Error | Cause | Resolution |
|-------|-------|------------|
| `EADDRINUSE` | Port already in use | `lsof -i :37777` then kill conflicting process |
| `No such process` | Stale PID file | Automatic cleanup on next hook trigger |
| `pm2: command not found` | PM2 not installed | None needed (error is caught and ignored) |
| `Invalid port X` | Port validation failed | Update `CLAUDE_MEM_WORKER_PORT` in settings |
## Developer Notes
### Testing the Migration
```bash
# 1. Install old version (with PM2)
git checkout <pre-7.1.0-tag>
npm install && npm run build && npm run sync-marketplace
# 2. Start PM2 worker
pm2 start plugin/scripts/worker-cli.js --name claude-mem-worker
# 3. Update to new version
git checkout main
npm install && npm run build && npm run sync-marketplace
# 4. Trigger hook
node plugin/scripts/session-start-hook.js
# 5. Verify migration
pm2 list # Should NOT show claude-mem-worker
cat ~/.claude-mem/.pm2-migrated # Should exist
npm run worker:status # Should show Bun worker running
```
### Architecture Decisions
**Why Custom ProcessManager Instead of PM2?**
1. **Simplicity**: Direct control, no external daemon
2. **Dependencies**: Remove npm dependency
3. **Cross-platform**: Bun handles platform differences
4. **Bundle Size**: Reduce plugin package size
5. **Control**: Fine-grained error handling and validation
**Why One-Time Marker Instead of Always Running PM2 Delete?**
1. **Performance**: Avoid unnecessary process spawning
2. **Idempotency**: Migration runs exactly once
3. **Debugging**: Timestamp shows when migration occurred
4. **Simplicity**: Clear migration state
**Why Run PM2 Cleanup on All Platforms?**
1. **Quality Migration**: Clean up orphaned processes
2. **Consistency**: Same behavior across all platforms
3. **Safety**: Error handling already in place (try/catch)
4. **No Downside**: If PM2 not installed, error is caught and ignored
## Summary
The migration from PM2 to Bun-based ProcessManager is a **one-time, automatic, transparent** transition that:
1. **Removes external dependencies** (PM2, better-sqlite3)
2. **Simplifies architecture** (direct process control)
3. **Improves cross-platform support** (especially Windows)
4. **Preserves user data** (database, settings, logs unchanged)
5. **Requires no user action** (automatic on first hook trigger)
**Key Migration Moment**: First hook trigger after update to 7.1.0+
**Duration**: ~2-5 seconds (one-time delay)
**Impact**: Seamless transition, user-invisible
**Rollback**: Not needed (migration is forward-only, safe)
For most users, the migration will be completely transparent - they'll see no errors, no data loss, and experience improved reliability and simpler troubleshooting going forward.

497
.agent/services/claude-mem/docs/public/architecture/search-architecture.mdx Normal file
View File

@@ -0,0 +1,497 @@
---
title: "Search Architecture"
description: "MCP tools with 3-layer workflow for token-efficient memory retrieval"
---
# Search Architecture
Claude-mem uses an **MCP-based search architecture** that provides intelligent memory retrieval through 4 streamlined tools following a 3-layer workflow pattern.
## Overview
**Architecture**: MCP Tools → MCP Protocol → HTTP API → Worker Service
**Key Components**:
1. **MCP Tools** (4 tools) - `search`, `timeline`, `get_observations`, `__IMPORTANT`
2. **MCP Server** (`plugin/scripts/mcp-server.cjs`) - Thin wrapper over HTTP API
3. **HTTP API Endpoints** - Fast search operations on Worker Service (port 37777)
4. **Worker Service** - Express.js server with FTS5 full-text search
5. **SQLite Database** - Persistent storage with FTS5 virtual tables
6. **Chroma Vector DB** - Semantic search with hybrid retrieval
**Token Efficiency**: ~10x savings through 3-layer workflow pattern
## How It Works
### 1. User Query
Claude has access to 4 MCP tools. When searching memory, Claude follows the 3-layer workflow:
```
Step 1: search(query="authentication bug", type="bugfix", limit=10)
Step 2: timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
Step 3: get_observations(ids=[123, 456, 789])
```
### 2. MCP Protocol
MCP server receives tool call via JSON-RPC over stdio:
```json
{
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "authentication bug",
"type": "bugfix",
"limit": 10
}
}
}
```
### 3. HTTP API Call
MCP server translates to HTTP request:
```typescript
const url = `http://localhost:37777/api/search?query=authentication%20bug&type=bugfix&limit=10`;
const response = await fetch(url);
```
### 4. Worker Processing
Worker service executes FTS5 query:
```sql
SELECT * FROM observations_fts
WHERE observations_fts MATCH ?
AND type = 'bugfix'
ORDER BY rank
LIMIT 10
```
### 5. Results Returned
Worker returns structured data → MCP server → Claude:
```json
{
"content": [{
"type": "text",
"text": "| ID | Time | Title | Type |\n|---|---|---|---|\n| #123 | 2:15 PM | Fixed auth token expiry | bugfix |"
}]
}
```
### 6. Claude Processes Results
Claude reviews the index, decides which observations are relevant, and can:
- Use `timeline` to get context
- Use `get_observations` to fetch full details for selected IDs
## The 4 MCP Tools
### `__IMPORTANT` - Workflow Documentation
Always visible to Claude. Explains the 3-layer workflow pattern.
**Description:**
```
3-LAYER WORKFLOW (ALWAYS FOLLOW):
1. search(query) → Get index with IDs (~50-100 tokens/result)
2. timeline(anchor=ID) → Get context around interesting results
3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs
NEVER fetch full details without filtering first. 10x token savings.
```
**Purpose:** Ensures Claude follows token-efficient pattern
### `search` - Search Memory Index
**Tool Definition:**
```typescript
{
name: 'search',
description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy',
inputSchema: {
type: 'object',
properties: {},
additionalProperties: true // Accepts any parameters
}
}
```
**HTTP Endpoint:** `GET /api/search`
**Parameters:**
- `query` - Full-text search query
- `limit` - Maximum results (default: 20)
- `type` - Filter by observation type
- `project` - Filter by project name
- `dateStart`, `dateEnd` - Date range filters
- `offset` - Pagination offset
- `orderBy` - Sort order
**Returns:** Compact index with IDs, titles, dates, types (~50-100 tokens per result)
### `timeline` - Get Chronological Context
**Tool Definition:**
```typescript
{
name: 'timeline',
description: 'Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project',
inputSchema: {
type: 'object',
properties: {},
additionalProperties: true
}
}
```
**HTTP Endpoint:** `GET /api/timeline`
**Parameters:**
- `anchor` - Observation ID to center timeline around (optional if query provided)
- `query` - Search query to find anchor automatically (optional if anchor provided)
- `depth_before` - Number of observations before anchor (default: 3)
- `depth_after` - Number of observations after anchor (default: 3)
- `project` - Filter by project name
**Returns:** Chronological view showing what happened before/during/after
### `get_observations` - Fetch Full Details
**Tool Definition:**
```typescript
{
name: 'get_observations',
description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project',
inputSchema: {
type: 'object',
properties: {
ids: {
type: 'array',
items: { type: 'number' },
description: 'Array of observation IDs to fetch (required)'
}
},
required: ['ids'],
additionalProperties: true
}
}
```
**HTTP Endpoint:** `POST /api/observations/batch`
**Body:**
```json
{
"ids": [123, 456, 789],
"orderBy": "date_desc",
"project": "my-app"
}
```
**Returns:** Complete observation details (~500-1,000 tokens per observation)
## MCP Server Implementation
**Location:** `/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs`
**Role:** Thin wrapper that translates MCP protocol to HTTP API calls
**Key Characteristics:**
- ~312 lines of code (reduced from ~2,718 lines in old implementation)
- No business logic - just protocol translation
- Single source of truth: Worker HTTP API
- Simple schemas with `additionalProperties: true`
**Handler Example:**
```typescript
{
name: 'search',
handler: async (args: any) => {
const endpoint = '/api/search';
const searchParams = new URLSearchParams();
for (const [key, value] of Object.entries(args)) {
searchParams.append(key, String(value));
}
const url = `http://localhost:37777${endpoint}?${searchParams}`;
const response = await fetch(url);
return await response.json();
}
}
```
## Worker HTTP API
**Location:** `src/services/worker-service.ts`
**Port:** 37777
**Search Endpoints:**
```typescript
GET /api/search # Main search (used by MCP search tool)
GET /api/timeline # Timeline context (used by MCP timeline tool)
POST /api/observations/batch # Fetch by IDs (used by MCP get_observations tool)
GET /api/health # Health check
```
**Database Access:**
- Uses `SessionSearch` service for FTS5 queries
- Uses `SessionStore` for structured queries
- Hybrid search with ChromaDB for semantic similarity
**FTS5 Full-Text Search:**
```typescript
// search tool → HTTP GET → FTS5 query
SELECT * FROM observations_fts
WHERE observations_fts MATCH ?
AND type = ?
AND date >= ? AND date <= ?
ORDER BY rank
LIMIT ? OFFSET ?
```
## The 3-Layer Workflow Pattern
### Design Philosophy
The 3-layer workflow embodies **progressive disclosure** - a core principle of claude-mem's architecture.
**Layer 1: Index (Search)**
- **What:** Compact table with IDs, titles, dates, types
- **Cost:** ~50-100 tokens per result
- **Purpose:** Survey what exists before committing tokens
- **Decision Point:** "Which observations are relevant?"
**Layer 2: Context (Timeline)**
- **What:** Chronological view of observations around a point
- **Cost:** Variable based on depth
- **Purpose:** Understand narrative arc, see what led to/from a point
- **Decision Point:** "Do I need full details?"
**Layer 3: Details (Get Observations)**
- **What:** Complete observation data (narrative, facts, files, concepts)
- **Cost:** ~500-1,000 tokens per observation
- **Purpose:** Deep dive on validated, relevant observations
- **Decision Point:** "Apply knowledge to current task"
### Token Efficiency
**Traditional RAG Approach:**
```
Fetch 20 observations upfront: 10,000-20,000 tokens
Relevance: ~10% (only 2 observations actually useful)
Waste: 18,000 tokens on irrelevant context
```
**3-Layer Workflow:**
```
Step 1: search (20 results) ~1,000-2,000 tokens
Step 2: Review index, filter to 3 relevant IDs
Step 3: get_observations (3 IDs) ~1,500-3,000 tokens
Total: 2,500-5,000 tokens (50-75% savings)
```
**10x Savings:** By filtering at index level before fetching full details
## Architecture Evolution
### Before: Complex MCP Implementation
**Approach:** 9 MCP tools with detailed parameter schemas
**Token Cost:** ~2,500 tokens in tool definitions per session
- `search_observations` - Full-text search
- `find_by_type` - Filter by type
- `find_by_file` - Filter by file
- `find_by_concept` - Filter by concept
- `get_recent_context` - Recent sessions
- `get_observation` - Fetch single observation
- `get_session` - Fetch session
- `get_prompt` - Fetch prompt
- `help` - API documentation
**Problems:**
- Overlapping operations (search_observations vs find_by_type)
- Complex parameter schemas
- No built-in workflow guidance
- High token cost at session start
**Code Size:** ~2,718 lines in mcp-server.ts
### After: Streamlined MCP Implementation
**Approach:** 4 MCP tools following 3-layer workflow
**Token Cost:** ~312 lines of code, simplified tool definitions
**Tools:**
1. `__IMPORTANT` - Workflow guidance (always visible)
2. `search` - Step 1 (index)
3. `timeline` - Step 2 (context)
4. `get_observations` - Step 3 (details)
**Benefits:**
- Progressive disclosure built into tool design
- No overlapping operations
- Simple schemas (`additionalProperties: true`)
- Clear workflow pattern
- ~10x token savings
**Code Size:** ~312 lines in mcp-server.ts (88% reduction)
### Key Insight
**Before:** Progressive disclosure was something Claude had to remember
**After:** Progressive disclosure is enforced by tool design itself
The 3-layer workflow pattern makes it structurally difficult to waste tokens:
- Can't fetch details without first getting IDs from search
- Can't search without seeing workflow reminder (`__IMPORTANT`)
- Timeline provides middle ground between index and full details
## Configuration
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mcp-search": {
"command": "node",
"args": [
"/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
]
}
}
}
```
### Claude Code
MCP server is automatically configured via plugin installation. No manual setup required.
**Both clients use the same MCP tools** - the architecture works identically for Claude Desktop and Claude Code.
## Security
### FTS5 Injection Prevention
All search queries are escaped before FTS5 processing:
```typescript
function escapeFTS5Query(query: string): string {
return query.replace(/"/g, '""');
}
```
**Testing:** 332 injection attack tests covering special characters, SQL keywords, quote escaping, and boolean operators.
### MCP Protocol Security
- Stdio transport (no network exposure)
- Local-only HTTP API (localhost:37777)
- No authentication needed (local development only)
## Performance
**FTS5 Full-Text Search:** Sub-10ms for typical queries
**MCP Overhead:** Minimal - simple protocol translation
**Caching:** HTTP layer allows response caching (future enhancement)
**Pagination:** Efficient with offset/limit
**Batching:** `get_observations` accepts multiple IDs in single call
## Benefits Over Alternative Approaches
### vs. Traditional RAG
**Traditional RAG:**
- Fetches everything upfront
- High token cost
- Low relevance ratio
**3-Layer MCP:**
- Fetches only what's needed
- ~10x token savings
- 100% relevance (Claude chooses what to fetch)
### vs. Previous MCP Implementation (v5.x)
**Previous (9 tools):**
- Complex schemas
- Overlapping operations
- No workflow guidance
- ~2,500 tokens in definitions
**Current (4 tools):**
- Simple schemas
- Clear workflow
- Built-in guidance
- ~312 lines of code
### vs. Skill-Based Approach (Previously)
**Skill approach:**
- Required separate skill files
- HTTP API called directly via curl
- Progressive disclosure through skill loading
**MCP approach:**
- Native MCP protocol (better Claude integration)
- Cleaner architecture (protocol translation layer)
- Works with both Claude Desktop and Claude Code
- Simpler to maintain (no skill files)
**Migration:** Skill-based search was removed in favor of streamlined MCP architecture.
## Troubleshooting
### MCP Server Not Connected
**Symptoms:** Tools not appearing in Claude
**Solution:**
1. Check MCP server path in configuration
2. Verify worker service is running: `curl http://localhost:37777/api/health`
3. Restart Claude Desktop/Code
### Worker Service Not Running
**Symptoms:** MCP tools fail with connection errors
**Solution:**
```bash
npm run worker:status # Check status
npm run worker:restart # Restart worker
npm run worker:logs # View logs
```
### Empty Search Results
**Symptoms:** search() returns no results
**Troubleshooting:**
1. Test API directly: `curl "http://localhost:37777/api/search?query=test"`
2. Check database: `ls ~/.claude-mem/claude-mem.db`
3. Verify observations exist: `curl "http://localhost:37777/api/health"`
## Next Steps
- [Memory Search Usage](/usage/search-tools) - User guide with examples
- [Progressive Disclosure](/progressive-disclosure) - Philosophy behind 3-layer workflow
- [Worker Service Architecture](/architecture/worker-service) - HTTP API details
- [Database Schema](/architecture/database) - FTS5 tables and indexes

695
.agent/services/claude-mem/docs/public/architecture/worker-service.mdx Normal file
View File

@@ -0,0 +1,695 @@
---
title: "Worker Service"
description: "HTTP API and Bun process management"
---
# Worker Service
The worker service is a long-running HTTP API built with Express.js and managed natively by Bun. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.
## Overview
- **Technology**: Express.js HTTP server
- **Runtime**: Bun (auto-installed if missing)
- **Process Manager**: Native Bun process management via ProcessManager
- **Port**: Fixed port 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`)
- **Location**: `src/services/worker-service.ts`
- **Built Output**: `plugin/scripts/worker-service.cjs`
- **Model**: Configurable via `CLAUDE_MEM_MODEL` environment variable (default: sonnet)
## REST API Endpoints
The worker service exposes 22 HTTP endpoints organized into six categories:
### Viewer & Health Endpoints
#### 1. Viewer UI
```
GET /
```
**Purpose**: Serves the web-based viewer UI (v5.1.0+)
**Response**: HTML page with embedded React application
**Features**:
- Real-time memory stream visualization
- Infinite scroll pagination
- Project filtering
- SSE-based live updates
- Theme toggle (light/dark mode) as of v5.1.2
#### 2. Health Check
```
GET /health
```
**Purpose**: Worker health status check
**Response**:
```json
{
"status": "ok",
"uptime": 12345,
"port": 37777
}
```
#### 3. Server-Sent Events Stream
```
GET /stream
```
**Purpose**: Real-time updates for viewer UI
**Response**: SSE stream with events:
- `observation-created`: New observation added
- `session-summary-created`: New summary generated
- `user-prompt-created`: New prompt recorded
**Event Format**:
```
event: observation-created
data: {"id": 123, "title": "...", ...}
```
### Data Retrieval Endpoints
#### 4. Get Prompts
```
GET /api/prompts?project=my-project&limit=20&offset=0
```
**Purpose**: Retrieve paginated user prompts
**Query Parameters**:
- `project` (optional): Filter by project name
- `limit` (default: 20): Number of results
- `offset` (default: 0): Pagination offset
**Response**:
```json
{
"prompts": [{
"id": 1,
"session_id": "abc123",
"prompt": "User's prompt text",
"prompt_number": 1,
"created_at": "2025-11-06T10:30:00Z"
}],
"total": 150,
"hasMore": true
}
```
#### 5. Get Observations
```
GET /api/observations?project=my-project&limit=20&offset=0
```
**Purpose**: Retrieve paginated observations
**Query Parameters**:
- `project` (optional): Filter by project name
- `limit` (default: 20): Number of results
- `offset` (default: 0): Pagination offset
**Response**:
```json
{
"observations": [{
"id": 123,
"title": "Fix authentication bug",
"type": "bugfix",
"narrative": "...",
"created_at": "2025-11-06T10:30:00Z"
}],
"total": 500,
"hasMore": true
}
```
#### 6. Get Summaries
```
GET /api/summaries?project=my-project&limit=20&offset=0
```
**Purpose**: Retrieve paginated session summaries
**Query Parameters**:
- `project` (optional): Filter by project name
- `limit` (default: 20): Number of results
- `offset` (default: 0): Pagination offset
**Response**:
```json
{
"summaries": [{
"id": 456,
"session_id": "abc123",
"request": "User's original request",
"completed": "Work finished",
"created_at": "2025-11-06T10:30:00Z"
}],
"total": 100,
"hasMore": true
}
```
#### 7. Get Observation by ID
```
GET /api/observation/:id
```
**Purpose**: Retrieve a single observation by its ID
**Path Parameters**:
- `id` (required): Observation ID
**Response**:
```json
{
"id": 123,
"sdk_session_id": "abc123",
"project": "my-project",
"type": "bugfix",
"title": "Fix authentication bug",
"narrative": "...",
"created_at": "2025-11-06T10:30:00Z",
"created_at_epoch": 1730886600000
}
```
**Error Response** (404):
```json
{
"error": "Observation #123 not found"
}
```
#### 8. Get Observations by IDs (Batch)
```
POST /api/observations/batch
```
**Purpose**: Retrieve multiple observations by their IDs in a single request
**Request Body**:
```json
{
"ids": [123, 456, 789],
"orderBy": "date_desc",
"limit": 10,
"project": "my-project"
}
```
**Body Parameters**:
- `ids` (required): Array of observation IDs
- `orderBy` (optional): Sort order - `date_desc` or `date_asc` (default: `date_desc`)
- `limit` (optional): Maximum number of results to return
- `project` (optional): Filter by project name
**Response**:
```json
[
{
"id": 789,
"sdk_session_id": "abc123",
"project": "my-project",
"type": "feature",
"title": "Add new feature",
"narrative": "...",
"created_at": "2025-11-06T12:00:00Z",
"created_at_epoch": 1730891400000
},
{
"id": 456,
"sdk_session_id": "abc124",
"project": "my-project",
"type": "bugfix",
"title": "Fix authentication bug",
"narrative": "...",
"created_at": "2025-11-06T10:30:00Z",
"created_at_epoch": 1730886600000
}
]
```
**Error Responses**:
- `400 Bad Request`: `{"error": "ids must be an array of numbers"}`
- `400 Bad Request`: `{"error": "All ids must be integers"}`
**Use Case**: This endpoint is used by the `get_observations` MCP tool to efficiently retrieve multiple observations in a single request, avoiding the overhead of multiple individual requests.
#### 9. Get Session by ID
```
GET /api/session/:id
```
**Purpose**: Retrieve a single session by its ID
**Path Parameters**:
- `id` (required): Session ID
**Response**:
```json
{
"id": 456,
"sdk_session_id": "abc123",
"project": "my-project",
"request": "User's original request",
"completed": "Work finished",
"created_at": "2025-11-06T10:30:00Z"
}
```
**Error Response** (404):
```json
{
"error": "Session #456 not found"
}
```
#### 10. Get Prompt by ID
```
GET /api/prompt/:id
```
**Purpose**: Retrieve a single user prompt by its ID
**Path Parameters**:
- `id` (required): Prompt ID
**Response**:
```json
{
"id": 1,
"session_id": "abc123",
"prompt": "User's prompt text",
"prompt_number": 1,
"created_at": "2025-11-06T10:30:00Z"
}
```
**Error Response** (404):
```json
{
"error": "Prompt #1 not found"
}
```
#### 12. Get Stats
```
GET /api/stats
```
**Purpose**: Get database statistics by project
**Response**:
```json
{
"byProject": {
"my-project": {
"observations": 245,
"summaries": 12,
"prompts": 48
},
"other-project": {
"observations": 156,
"summaries": 8,
"prompts": 32
}
},
"total": {
"observations": 401,
"summaries": 20,
"prompts": 80,
"sessions": 20
}
}
```
#### 13. Get Projects
```
GET /api/projects
```
**Purpose**: Get list of distinct projects from observations
**Response**:
```json
{
"projects": ["my-project", "other-project", "test-project"]
}
```
### Settings Endpoints
#### 14. Get Settings
```
GET /api/settings
```
**Purpose**: Retrieve user settings
**Response**:
```json
{
"sidebarOpen": true,
"selectedProject": "my-project",
"theme": "dark"
}
```
#### 15. Save Settings
```
POST /api/settings
```
**Purpose**: Persist user settings
**Request Body**:
```json
{
"sidebarOpen": false,
"selectedProject": "other-project",
"theme": "light"
}
```
**Response**:
```json
{
"success": true
}
```
### Queue Management Endpoints
#### 16. Get Pending Queue Status
```
GET /api/pending-queue
```
**Purpose**: View current processing queue status and identify stuck messages
**Response**:
```json
{
"queue": {
"messages": [
{
"id": 123,
"session_db_id": 45,
"claude_session_id": "abc123",
"message_type": "observation",
"status": "pending",
"retry_count": 0,
"created_at_epoch": 1730886600000,
"started_processing_at_epoch": null,
"completed_at_epoch": null
}
],
"totalPending": 5,
"totalProcessing": 2,
"totalFailed": 0,
"stuckCount": 1
},
"recentlyProcessed": [
{
"id": 122,
"session_db_id": 44,
"status": "processed",
"completed_at_epoch": 1730886500000
}
],
"sessionsWithPendingWork": [44, 45, 46]
}
```
**Status Definitions**:
- `pending`: Message queued, not yet processed
- `processing`: Message currently being processed by SDK agent
- `processed`: Message completed successfully
- `failed`: Message failed after max retry attempts (3 by default)
**Stuck Detection**: Messages in `processing` status for >5 minutes are considered stuck and included in `stuckCount`
**Use Case**: Check queue health after worker crashes or restarts to identify unprocessed observations
#### 17. Trigger Manual Recovery
```
POST /api/pending-queue/process
```
**Purpose**: Manually trigger processing of pending queues (replaces automatic recovery in v5.x+)
**Request Body**:
```json
{
"sessionLimit": 10
}
```
**Body Parameters**:
- `sessionLimit` (optional): Maximum number of sessions to process (default: 10, max: 100)
**Response**:
```json
{
"success": true,
"totalPendingSessions": 15,
"sessionsStarted": 10,
"sessionsSkipped": 2,
"startedSessionIds": [44, 45, 46, 47, 48, 49, 50, 51, 52, 53]
}
```
**Response Fields**:
- `totalPendingSessions`: Total sessions with pending messages in database
- `sessionsStarted`: Number of sessions we started processing this request
- `sessionsSkipped`: Sessions already actively processing (not restarted)
- `startedSessionIds`: Database IDs of sessions started
**Behavior**:
- Processes up to `sessionLimit` sessions with pending work
- Skips sessions already actively processing (prevents duplicate agents)
- Starts non-blocking SDK agents for each session
- Returns immediately with status (processing continues in background)
**Use Case**: Manually recover stuck observations after worker crashes, or when automatic recovery was disabled
**Recovery Strategy Note**: As of v5.x, automatic recovery on worker startup is disabled by default. Users must manually trigger recovery using this endpoint or the CLI tool (`bun scripts/check-pending-queue.ts`) to maintain explicit control over reprocessing.
### Session Management Endpoints
#### 19. Initialize Session
```
POST /sessions/:sessionDbId/init
```
**Request Body**:
```json
{
"sdk_session_id": "abc-123",
"project": "my-project"
}
```
**Response**:
```json
{
"success": true,
"session_id": "abc-123"
}
```
#### 20. Add Observation
```
POST /sessions/:sessionDbId/observations
```
**Request Body**:
```json
{
"tool_name": "Read",
"tool_input": {...},
"tool_result": "...",
"correlation_id": "xyz-789"
}
```
**Response**:
```json
{
"success": true,
"observation_id": 123
}
```
#### 21. Generate Summary
```
POST /sessions/:sessionDbId/summarize
```
**Request Body**:
```json
{
"trigger": "stop"
}
```
**Response**:
```json
{
"success": true,
"summary_id": 456
}
```
#### 22. Session Status
```
GET /sessions/:sessionDbId/status
```
**Response**:
```json
{
"session_id": "abc-123",
"status": "active",
"observation_count": 42,
"summary_count": 1
}
```
#### 23. Delete Session
```
DELETE /sessions/:sessionDbId
```
**Response**:
```json
{
"success": true
}
```
**Note**: As of v4.1.0, the cleanup hook no longer calls this endpoint. Sessions are marked complete instead of deleted to allow graceful worker shutdown.
## Bun Process Management
### Overview
The worker is managed by the native `ProcessManager` class which handles:
- Process spawning with Bun runtime
- PID file tracking at `~/.claude-mem/worker.pid`
- Health checks with automatic retry
- Graceful shutdown with SIGTERM/SIGKILL fallback
### Commands
```bash
# Start worker (auto-starts on first session)
npm run worker:start
# Stop worker
npm run worker:stop
# Restart worker
npm run worker:restart
# View logs
npm run worker:logs
# Check status
npm run worker:status
```
### Auto-Start Behavior
The worker service auto-starts when the SessionStart hook fires. Manual start is optional.
### Bun Requirement
Bun is required to run the worker service. If Bun is not installed, the smart-install script will automatically install it on first run:
- **Windows**: `powershell -c "irm bun.sh/install.ps1 | iex"`
- **macOS/Linux**: `curl -fsSL https://bun.sh/install | bash`
You can also install manually via:
- `winget install Oven-sh.Bun` (Windows)
- `brew install oven-sh/bun/bun` (macOS)
## Claude Agent SDK Integration
The worker service routes observations to the Claude Agent SDK for AI-powered processing:
### Processing Flow
1. **Observation Queue**: Observations accumulate in memory
2. **SDK Processing**: Observations sent to Claude via Agent SDK
3. **XML Parsing**: Responses parsed for structured data
4. **Database Storage**: Processed observations stored in SQLite
### SDK Components
- **Prompts** (`src/sdk/prompts.ts`): Builds XML-structured prompts
- **Parser** (`src/sdk/parser.ts`): Parses Claude's XML responses
- **Worker** (`src/sdk/worker.ts`): Main SDK agent loop
### Model Configuration
Set the AI model used for processing via environment variable:
```bash
export CLAUDE_MEM_MODEL=sonnet
```
Available shorthand models (forward to latest version):
- `haiku` - Fast, cost-efficient
- `sonnet` - Balanced (default)
- `opus` - Most capable
## Port Allocation
The worker uses a fixed port (37777 by default) for consistent communication:
- **Default**: Port 37777
- **Override**: Set `CLAUDE_MEM_WORKER_PORT` environment variable
- **Port File**: `${CLAUDE_PLUGIN_ROOT}/data/worker.port` tracks current port
If port 37777 is in use, the worker will fail to start. Set a custom port via environment variable.
## Data Storage
The worker service stores data in the user data directory:
```
~/.claude-mem/
├── claude-mem.db # SQLite database (bun:sqlite)
├── worker.pid # PID file for process tracking
├── settings.json # User settings
└── logs/
└── worker-YYYY-MM-DD.log # Daily rotating logs
```
## Error Handling
The worker implements graceful degradation:
- **Database Errors**: Logged but don't crash the service
- **SDK Errors**: Retried with exponential backoff
- **Network Errors**: Logged and skipped
- **Invalid Input**: Validated and rejected with error response
## Performance
- **Async Processing**: Observations processed asynchronously
- **In-Memory Queue**: Fast observation accumulation
- **Batch Processing**: Multiple observations processed together
- **Connection Pooling**: SQLite connections reused
## Troubleshooting
See [Troubleshooting - Worker Issues](../troubleshooting.md#worker-service-issues) for common problems and solutions.

151
.agent/services/claude-mem/docs/public/beta-features.mdx Normal file
View File

@@ -0,0 +1,151 @@
---
title: "Beta Features"
description: "Try experimental features like Endless Mode before they're released"
---
# Beta Features
<Warning>
**Endless Mode is experimental and not included in the stable release.** You must manually switch to the beta branch to try it. The efficiency projections below are based on theoretical modeling, not production measurements. Expect slower performance than standard mode and potential bugs.
</Warning>
Claude-Mem offers a beta channel for users who want to try experimental features before they're released to the stable channel.
## Version Channel Switching
You can switch between stable and beta versions directly from the web viewer UI at http://localhost:37777.
### How to Access
1. Open the Claude-Mem viewer at http://localhost:37777
2. Click the **Settings** gear icon in the top-right
3. Find the **Version Channel** section
4. Click **Try Beta (Endless Mode)** to switch to beta, or **Switch to Stable** to return
### What Happens When You Switch
When switching versions:
1. **Local changes are discarded** - Any modifications in the plugin directory are reset
2. **Git fetch and checkout** - The installed plugin switches to the target branch
3. **Dependencies reinstall** - `npm install` runs to ensure correct dependencies
4. **Worker restarts automatically** - The background service restarts with the new version
**Your memory data is always preserved.** The database at `~/.claude-mem/claude-mem.db` is not affected by version switching. All your observations, sessions, and summaries remain intact.
### Version Indicators
The Version Channel section shows your current status:
- **Stable** (green badge) - You're running the production release
- **Beta** (orange badge) - You're running the beta with experimental features
You'll also see the exact branch name (e.g., `main` for stable, `beta/7.0` for beta).
## Endless Mode (Beta)
The flagship experimental feature in beta is **Endless Mode** - a biomimetic memory architecture that dramatically extends how long Claude can maintain context in a session.
### The Problem Endless Mode Solves
In standard Claude Code sessions:
- Tool outputs (file reads, bash output, search results) accumulate in the context window
- Each tool can add 1-10k+ tokens to the context
- After ~50 tool uses, the context window fills up (~200k tokens)
- You're forced to start a new session, losing conversational continuity
Worse, Claude **re-synthesizes all previous tool outputs** on every response. This is O(N²) complexity - quadratically growing both in tokens and compute.
### How Endless Mode Works
Endless Mode applies a biomimetic memory architecture inspired by how human memory works:
**Two-Tier Memory System:**
```
Working Memory (Context Window):
→ Compressed observations only (~500 tokens each)
→ Fast, efficient, manageable
Archive Memory (Transcript File):
→ Full tool outputs preserved on disk
→ Perfect recall, searchable
```
**The Key Innovation**: After each tool use, Endless Mode:
1. Waits for the worker to generate a compressed observation (blocking)
2. Transforms the transcript file on disk
3. Replaces the full tool output with the compressed observation
4. Claude resumes with the compressed context
This transforms O(N²) scaling into O(N) - linear instead of quadratic.
### Projected Results
Based on theoretical modeling (not production measurements):
- **Token savings**: Significant reduction in context window usage
- **Efficiency gain**: More tool uses before context exhaustion
- **Quality preservation**: Observations cache the synthesis result, so no information is lost
### Important Caveats
Endless Mode is experimental and has significant limitations:
- **Not in stable release** - You must manually switch to the beta branch to use this feature
- **Still in development** - May have bugs, breaking changes, or incomplete functionality
- **Slower than standard mode** - Blocking observation generation adds latency to each tool use
- **Theoretical projections** - The efficiency claims above are based on simulations, not real-world production data
- **Requires working database** - Observations must save successfully for transformation
- **New architecture** - Less battle-tested than standard mode
### When to Use Beta
Consider switching to beta if you:
- Frequently hit context window limits
- Work on long, complex sessions with many tool uses
- Want to help test and provide feedback on new features
- Are comfortable with experimental software
### When to Stay on Stable
Stay on stable if you:
- Need maximum reliability for critical work
- Prefer battle-tested, production-ready features
- Don't frequently hit context limits
- Want the smoothest, fastest experience
## Checking for Updates
While on beta (or stable), you can check for updates:
1. Open Settings in the viewer
2. In the Version Channel section, click **Check for Updates**
3. The plugin will pull the latest changes and restart
## Switching Back
If you encounter issues on beta:
1. Open Settings in the viewer
2. Click **Switch to Stable**
3. Wait for the worker to restart
Your memory data is preserved, and you'll be back on the stable release.
## Providing Feedback
If you encounter bugs or have feedback about beta features:
- Open an issue at [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- Include your branch (`beta/7.0` etc.) in the report
- Describe what you expected vs. what happened
## Next Steps
- [Configuration](configuration) - Customize other Claude-Mem settings
- [Troubleshooting](troubleshooting) - Common issues and solutions
- [Architecture Overview](architecture/overview) - Understand how Claude-Mem works

BIN
.agent/services/claude-mem/docs/public/claude-mem-logo-for-dark-mode.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

BIN
.agent/services/claude-mem/docs/public/claude-mem-logo-for-light-mode.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

BIN
.agent/services/claude-mem/docs/public/claude-mem-logomark.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
.agent/services/claude-mem/docs/public/cm-preview.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 MiB

505
.agent/services/claude-mem/docs/public/configuration.mdx Normal file
View File

@@ -0,0 +1,505 @@
---
title: "Configuration"
description: "Environment variables and settings for Claude-Mem"
---
# Configuration
## Settings File
Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created with defaults on first run.
### Core Settings
| Setting | Default | Description |
|-------------------------------|---------------------------------|---------------------------------------|
| `CLAUDE_MEM_MODEL` | `sonnet` | AI model for processing observations (when using Claude) |
| `CLAUDE_MEM_PROVIDER` | `claude` | AI provider: `claude`, `gemini`, or `openrouter` |
| `CLAUDE_MEM_MODE` | `code` | Active mode profile (e.g., `code--es`, `email-investigation`) |
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50` | Number of observations to inject |
| `CLAUDE_MEM_WORKER_PORT` | `37777` | Worker service port |
| `CLAUDE_MEM_WORKER_HOST` | `127.0.0.1` | Worker service host address |
| `CLAUDE_MEM_SKIP_TOOLS` | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
### Gemini Provider Settings
| Setting | Default | Description |
|-------------------------------|---------------------------------|---------------------------------------|
| `CLAUDE_MEM_GEMINI_API_KEY` | — | Gemini API key ([get free key](https://aistudio.google.com/app/apikey)) |
| `CLAUDE_MEM_GEMINI_MODEL` | `gemini-2.5-flash-lite` | Gemini model: `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash-preview` |
See [Gemini Provider](usage/gemini-provider) for detailed configuration and free tier information.
### OpenRouter Provider Settings
| Setting | Default | Description |
|----------------------------------------------|-----------------------------|---------------------------------------|
| `CLAUDE_MEM_OPENROUTER_API_KEY` | — | OpenRouter API key ([get key](https://openrouter.ai/keys)) |
| `CLAUDE_MEM_OPENROUTER_MODEL` | `xiaomi/mimo-v2-flash:free` | Model identifier (supports 100+ models) |
| `CLAUDE_MEM_OPENROUTER_MAX_CONTEXT_MESSAGES` | `20` | Max messages in conversation history |
| `CLAUDE_MEM_OPENROUTER_MAX_TOKENS` | `100000` | Token budget safety limit |
| `CLAUDE_MEM_OPENROUTER_SITE_URL` | — | Optional: URL for analytics |
| `CLAUDE_MEM_OPENROUTER_APP_NAME` | `claude-mem` | Optional: App name for analytics |
See [OpenRouter Provider](usage/openrouter-provider) for detailed configuration, free model list, and usage guide.
### System Configuration
| Setting | Default | Description |
|-------------------------------|---------------------------------|---------------------------------------|
| `CLAUDE_MEM_DATA_DIR` | `~/.claude-mem` | Data directory location |
| `CLAUDE_MEM_LOG_LEVEL` | `INFO` | Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT) |
| `CLAUDE_MEM_PYTHON_VERSION` | `3.13` | Python version for chroma-mcp |
| `CLAUDE_CODE_PATH` | _(auto-detect)_ | Path to Claude Code CLI (for Windows) |
## Model Configuration
Configure which AI model processes your observations.
### Available Models
Shorthand model names automatically forward to the latest version:
- `haiku` - Fast, cost-efficient
- `sonnet` - Balanced (default)
- `opus` - Most capable
### Using the Interactive Script
```bash
./claude-mem-settings.sh
```
This script manages settings in `~/.claude-mem/settings.json`.
### Manual Configuration
Edit `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_MODEL": "sonnet"
}
```
## Mode Configuration
Configure the active workflow mode and language.
### Settings
| Setting | Default | Description |
|---------|---------|-------------|
| `CLAUDE_MEM_MODE` | `code` | Defines behavior and language. See [Modes & Languages](modes). |
### Examples
**Spanish Code Mode:**
```json
{
"CLAUDE_MEM_MODE": "code--es"
}
```
**Email Investigation Mode:**
```json
{
"CLAUDE_MEM_MODE": "email-investigation"
}
```
## Files and Directories
### Data Directory Structure
The data directory location depends on the environment:
- **Production (installed plugin)**: `~/.claude-mem/` (always, regardless of CLAUDE_PLUGIN_ROOT)
- **Development**: Can be overridden with `CLAUDE_MEM_DATA_DIR`
```
~/.claude-mem/
├── claude-mem.db # SQLite database
├── .install-version # Cached version for smart installer
├── worker.port # Current worker port file
└── logs/
├── worker-out.log # Worker stdout logs
└── worker-error.log # Worker stderr logs
```
### Plugin Directory Structure
```
${CLAUDE_PLUGIN_ROOT}/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── .mcp.json # MCP server configuration
├── hooks/
│ └── hooks.json # Hook configuration
├── scripts/ # Built executables
│ ├── smart-install.js # Smart installer script
│ ├── context-hook.js # Context injection hook
│ ├── new-hook.js # Session creation hook
│ ├── save-hook.js # Observation capture hook
│ ├── summary-hook.js # Summary generation hook
│ ├── worker-service.cjs # Worker service (CJS)
│ └── mcp-server.cjs # MCP search server (CJS)
└── ui/
└── viewer.html # Web viewer UI bundle
```
## Plugin Configuration
### Hooks Configuration
Hooks are configured in `plugin/hooks/hooks.json`:
```json
{
"description": "Claude-mem memory system hooks",
"hooks": {
"SessionStart": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js && node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
"timeout": 120
}]
}],
"UserPromptSubmit": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js",
"timeout": 120
}]
}],
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js",
"timeout": 120
}]
}],
"Stop": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js",
"timeout": 120
}]
}]
}
}
```
### Search Configuration
Claude-Mem provides MCP search tools for querying your project history.
**No configuration required** - MCP tools are automatically available in Claude Code sessions.
Search operations are provided via:
- **MCP Server**: 3 tools (search, timeline, get_observations) with progressive disclosure
- **HTTP API**: 10 endpoints on worker service port 37777
- **Auto-Invocation**: Claude recognizes natural language queries about past work
## Version Channel
Claude-Mem supports switching between stable and beta versions via the web viewer UI.
### Accessing Version Channel
1. Open the viewer at http://localhost:37777
2. Click the Settings gear icon
3. Find the **Version Channel** section
### Switching Versions
- **Try Beta**: Click "Try Beta (Endless Mode)" to switch to the beta branch with experimental features
- **Switch to Stable**: Click "Switch to Stable" to return to the production release
- **Check for Updates**: Pull the latest changes for your current branch
**Your memory data is preserved** when switching versions. Only the plugin code changes.
<Note>
Endless Mode is experimental and slower than standard mode. See [Beta Features](beta-features) for full details and important limitations.
</Note>
## Worker Service Management
Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.
## Folder Context Files
Claude-mem can automatically generate `CLAUDE.md` files in your project folders with activity timelines. This feature is disabled by default.
| Setting | Default | Description |
|---------|---------|-------------|
| `CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED` | `false` | Enable auto-generation of folder CLAUDE.md files |
See [Folder Context Files](usage/folder-context) for full documentation on how this feature works, configuration options, and git integration recommendations.
## Context Injection Configuration
Claude-Mem injects past observations into each new session, giving Claude awareness of recent work. You can configure exactly what gets injected using the **Context Settings Modal**.
### Context Settings Modal
Access the settings modal from the web viewer at http://localhost:37777:
1. Click the **gear icon** in the header
2. Adjust settings in the right panel
3. See changes reflected live in the **Terminal Preview** on the left
4. Settings auto-save as you change them
The Terminal Preview shows exactly what will be injected at the start of your next Claude Code session for the selected project.
### Loading Settings
Control how many observations are injected:
| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| **Observations** | 50 | 1-200 | Total number of recent observations to include |
| **Sessions** | 10 | 1-50 | Number of recent sessions to pull observations from |
**Considerations**:
- **Higher values** = More context but slower SessionStart and more tokens used
- **Lower values** = Faster SessionStart but less historical awareness
- Default of 50 observations from 10 sessions balances context richness with performance
### Filter Settings
Control which observation types and concepts are included:
**Types** (select any combination):
- `bugfix` - Bug fixes and error resolutions
- `feature` - New functionality additions
- `refactor` - Code restructuring
- `discovery` - Learnings about how code works
- `decision` - Architectural or design decisions
- `change` - General code changes
**Concepts** (select any combination):
- `how-it-works` - System behavior explanations
- `why-it-exists` - Rationale for code/design
- `what-changed` - Change summaries
- `problem-solution` - Problem/solution pairs
- `gotcha` - Edge cases and pitfalls
- `pattern` - Recurring patterns
- `trade-off` - Design trade-offs
Use "All" or "None" buttons to quickly select/deselect all options.
### Display Settings
Control how observations appear in the context:
**Full Observations**:
| Setting | Default | Options | Description |
|---------|---------|---------|-------------|
| **Count** | 5 | 0-20 | How many observations show expanded details |
| **Field** | narrative | narrative, facts | Which field to expand |
The most recent N observations (set by Count) show their full narrative or facts. Remaining observations show only title, type, and token counts in a compact table format.
**Token Economics** (toggles):
| Setting | Default | Description |
|---------|---------|-------------|
| **Read cost** | true | Show tokens to read each observation |
| **Work investment** | true | Show tokens spent creating the observation |
| **Savings** | true | Show total tokens saved by reusing context |
Token economics help you understand the value of cached observations vs. re-reading files.
### Advanced Settings
| Setting | Default | Description |
|---------|---------|-------------|
| **Model** | sonnet | AI model for generating observations |
| **Worker Port** | 37777 | Port for background worker service |
| **MCP search server** | true | Enable Model Context Protocol search tools |
| **Include last summary** | false | Add previous session's summary to context |
| **Include last message** | false | Add previous session's final message |
### Manual Configuration
Settings are stored in `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
"CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
"CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
"CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
"CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
"CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
"CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
"CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
"CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
"CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
"CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
}
```
**Note**: The Context Settings Modal (at http://localhost:37777) is the recommended way to configure these settings, as it provides live preview of changes.
## Customization
Settings can be customized in `~/.claude-mem/settings.json`.
### Custom Data Directory
Edit `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_DATA_DIR": "/custom/path"
}
```
### Custom Worker Port
Edit `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_WORKER_PORT": "38000"
}
```
Then restart the worker:
```bash
npm run worker:restart
```
### Custom Model
Edit `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_MODEL": "opus"
}
```
Then restart the worker:
```bash
export CLAUDE_MEM_MODEL=opus
npm run worker:restart
```
### Custom Skip Tools
Control which tools are excluded from observations. Edit `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_SKIP_TOOLS": "ListMcpResourcesTool,SlashCommand,Skill"
}
```
**Default excluded tools:**
- `ListMcpResourcesTool`
- `SlashCommand`
- `Skill`
- `TodoWrite`
- `AskUserQuestion`
**Common customizations:**
- Include TodoWrite: Remove from skip list to track task planning
- Include AskUserQuestion: Remove to capture decision-making conversations
- Skip additional tools: Add tool names to reduce observation noise
Changes take effect on the next tool execution (no worker restart needed).
## Advanced Configuration
### Hook Timeouts
Modify timeouts in `plugin/hooks/hooks.json`:
```json
{
"timeout": 120 // Default: 120 seconds
}
```
Recommended values:
- SessionStart: 120s (needs time for smart install check and context retrieval)
- UserPromptSubmit: 60s
- PostToolUse: 120s (can process many observations)
- Stop: 60s
- SessionEnd: 60s
**Note**: With smart install caching (v5.0.3+), SessionStart is typically very fast (10ms) unless dependencies need installation.
### Worker Memory Limit
The worker service is managed by Bun and will automatically restart if it encounters issues. Memory usage is typically low (~100-200MB).
### Logging Verbosity
Enable debug logging:
```bash
export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs
```
## Configuration Best Practices
1. **Use defaults**: Default configuration works for most use cases
2. **Override selectively**: Only change what you need
3. **Document changes**: Keep track of custom configurations
4. **Test after changes**: Verify worker restarts successfully
5. **Monitor logs**: Check worker logs after configuration changes
## Troubleshooting Configuration
### Configuration Not Applied
1. Restart worker after changes:
```bash
npm run worker:restart
```
2. Verify environment variables:
```bash
echo $CLAUDE_MEM_MODEL
echo $CLAUDE_MEM_WORKER_PORT
```
3. Check worker logs:
```bash
npm run worker:logs
```
### Invalid Model Name
If you specify an invalid model name, the worker will fall back to `sonnet` and log a warning.
Valid shorthand models (forward to latest version):
- haiku
- sonnet
- opus
### Port Already in Use
If port 37777 is already in use:
1. Set custom port:
```bash
export CLAUDE_MEM_WORKER_PORT=38000
```
2. Restart worker:
```bash
npm run worker:restart
```
3. Verify new port:
```bash
cat ~/.claude-mem/worker.port
```
## Next Steps
- [Architecture Overview](architecture/overview) - Understand the system
- [Troubleshooting](troubleshooting) - Common issues
- [Development](development) - Building from source

227
.agent/services/claude-mem/docs/public/context-engineering.mdx Normal file
View File

@@ -0,0 +1,227 @@
---
title: "Context Engineering"
description: "Best practices for curating optimal token sets for AI agents"
---
# Context Engineering for AI Agents
## Core Principle
**Find the smallest possible set of high-signal tokens that maximize the likelihood of your desired outcome.**
---
## Context Engineering vs Prompt Engineering
**Prompt Engineering**: Writing and organizing LLM instructions for optimal outcomes (one-time task)
**Context Engineering**: Curating and maintaining the optimal set of tokens during inference across multiple turns (iterative process)
Context engineering manages:
- System instructions
- Tools
- Model Context Protocol (MCP)
- External data
- Message history
- Runtime data retrieval
---
## The Problem: Context Rot
**Key Insight**: LLMs have an "attention budget" that gets depleted as context grows
- Every token attends to every other token (n² relationships)
- As context length increases, model accuracy decreases
- Models have less training experience with longer sequences
- Context must be treated as a finite resource with diminishing marginal returns
---
## System Prompts: Find the "Right Altitude"
### The Goldilocks Zone
**Too Prescriptive** ❌
- Hardcoded if-else logic
- Brittle and fragile
- High maintenance complexity
**Too Vague** ❌
- High-level guidance without concrete signals
- Falsely assumes shared context
- Lacks actionable direction
**Just Right** ✅
- Specific enough to guide behavior effectively
- Flexible enough to provide strong heuristics
- Minimal set of information that fully outlines expected behavior
### Best Practices
- Use simple, direct language
- Organize into distinct sections (`<background_information>`, `<instructions>`, `## Tool guidance`, etc.)
- Use XML tags or Markdown headers for structure
- Start with minimal prompt, add based on failure modes
- Note: Minimal ≠ short (provide sufficient information upfront)
---
## Tools: Minimal and Clear
### Design Principles
- **Self-contained**: Each tool has a single, clear purpose
- **Robust to error**: Handle edge cases gracefully
- **Extremely clear**: Intended use is unambiguous
- **Token-efficient**: Returns relevant information without bloat
- **Descriptive parameters**: Unambiguous input names (e.g., `user_id` not `user`)
### Critical Rule
**If a human engineer can't definitively say which tool to use in a given situation, an AI agent can't be expected to do better.**
### Common Failure Modes to Avoid
- Bloated tool sets covering too much functionality
- Tools with overlapping purposes
- Ambiguous decision points about which tool to use
---
## Examples: Diverse, Not Exhaustive
**Do** ✅
- Curate a set of diverse, canonical examples
- Show expected behavior effectively
- Think "pictures worth a thousand words"
**Don't** ❌
- Stuff in a laundry list of edge cases
- Try to articulate every possible rule
- Overwhelm with exhaustive scenarios
---
## Context Retrieval Strategies
### Just-In-Time Context (Recommended for Agents)
**Approach**: Maintain lightweight identifiers (file paths, queries, links) and dynamically load data at runtime
**Benefits**:
- Avoids context pollution
- Enables progressive disclosure
- Mirrors human cognition (we don't memorize everything)
- Leverages metadata (file names, folder structure, timestamps)
- Agents discover context incrementally
**Trade-offs**:
- Slower than pre-computed retrieval
- Requires proper tool guidance to avoid dead-ends
### Pre-Inference Retrieval (Traditional RAG)
**Approach**: Use embedding-based retrieval to surface context before inference
**When to Use**: Static content that won't change during interaction
### Hybrid Strategy (Best of Both)
**Approach**: Retrieve some data upfront, enable autonomous exploration as needed
**Example**: Claude Code loads CLAUDE.md files upfront, uses glob/grep for just-in-time retrieval
**Rule of Thumb**: "Do the simplest thing that works"
---
## Long-Horizon Tasks: Three Techniques
### 1. Compaction
**What**: Summarize conversation nearing context limit, reinitiate with summary
**Implementation**:
- Pass message history to model for compression
- Preserve critical details (architectural decisions, bugs, implementation)
- Discard redundant outputs
- Continue with compressed context + recently accessed files
**Tuning Process**:
1. **First**: Maximize recall (capture all relevant information)
2. **Then**: Improve precision (eliminate superfluous content)
**Low-Hanging Fruit**: Clear old tool calls and results
**Best For**: Tasks requiring extensive back-and-forth
### 2. Structured Note-Taking (Agentic Memory)
**What**: Agent writes notes persisted outside context window, retrieved later
**Examples**:
- To-do lists
- NOTES.md files
- Game state tracking (Pokémon example: tracking 1,234 steps of training)
- Project progress logs
**Benefits**:
- Persistent memory with minimal overhead
- Maintains critical context across tool calls
- Enables multi-hour coherent strategies
**Best For**: Iterative development with clear milestones
### 3. Sub-Agent Architectures
**What**: Specialized sub-agents handle focused tasks with clean context windows
**How It Works**:
- Main agent coordinates high-level plan
- Sub-agents perform deep technical work
- Sub-agents explore extensively (tens of thousands of tokens)
- Return condensed summaries (1,000-2,000 tokens)
**Benefits**:
- Clear separation of concerns
- Parallel exploration
- Detailed context remains isolated
**Best For**: Complex research and analysis tasks
---
## Quick Decision Framework
| Scenario | Recommended Approach |
|----------|---------------------|
| Static content | Pre-inference retrieval or hybrid |
| Dynamic exploration needed | Just-in-time context |
| Extended back-and-forth | Compaction |
| Iterative development | Structured note-taking |
| Complex research | Sub-agent architectures |
| Rapid model improvement | "Do the simplest thing that works" |
---
## Key Takeaways
1. **Context is finite**: Treat it as a precious resource with an attention budget
2. **Think holistically**: Consider the entire state available to the LLM
3. **Stay minimal**: More context isn't always better
4. **Be iterative**: Context curation happens each time you pass to the model
5. **Design for autonomy**: As models improve, let them act intelligently
6. **Start simple**: Test with minimal setup, add based on failure modes
---
## Anti-Patterns to Avoid
- ❌ Cramming everything into prompts
- ❌ Creating brittle if-else logic
- ❌ Building bloated tool sets
- ❌ Stuffing exhaustive edge cases as examples
- ❌ Assuming larger context windows solve everything
- ❌ Ignoring context pollution over long interactions
---
## Remember
> "Even as models continue to improve, the challenge of maintaining coherence across extended interactions will remain central to building more effective agents."
Context engineering will evolve, but the core principle stays the same: **optimize signal-to-noise ratio in your token budget**.
---
*Based on Anthropic's "Effective context engineering for AI agents" (September 2025)*

191
.agent/services/claude-mem/docs/public/cursor/gemini-setup.mdx Normal file
View File

@@ -0,0 +1,191 @@
---
title: "Cursor + Gemini Setup"
description: "Use Claude-Mem in Cursor with Google's free Gemini API"
---
# Cursor + Gemini Setup
This guide walks you through setting up Claude-Mem in Cursor using Google's Gemini API. Gemini offers a generous free tier that handles typical individual usage.
<Info>
**Free Tier:** 1,500 requests per day with `gemini-2.5-flash-lite`. No credit card required.
</Info>
## Step 1: Get a Gemini API Key
1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
2. Sign in with your Google account
3. Accept the Terms of Service
4. Click **Create API key**
5. Choose or create a Google Cloud project
6. Copy your API key - you'll need it in Step 3
<Tip>
**Higher rate limits:** Enable billing on your Google Cloud project to unlock 4,000 RPM (vs 10 RPM without billing). You won't be charged unless you exceed the free quota.
</Tip>
## Step 2: Clone and Build Claude-Mem
```bash
# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# Install dependencies
bun install
# Build the project
bun run build
```
## Step 3: Configure Gemini Provider
### Option A: Interactive Setup (Recommended)
Run the setup wizard which guides you through everything:
```bash
bun run cursor:setup
```
The wizard will:
1. Detect you don't have Claude Code
2. Ask you to choose Gemini as your provider
3. Prompt for your API key
4. Install hooks automatically
5. Start the worker
### Option B: Manual Configuration
Create the settings file manually:
```bash
# Create settings directory
mkdir -p ~/.claude-mem
# Create settings file with Gemini configuration
cat > ~/.claude-mem/settings.json << 'EOF'
{
"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
EOF
```
Replace `YOUR_GEMINI_API_KEY` with your actual API key.
Then install hooks and start the worker:
```bash
bun run cursor:install
bun run worker:start
```
## Step 4: Restart Cursor
Close and reopen Cursor IDE for the hooks to take effect.
## Step 5: Verify Installation
```bash
# Check worker is running
bun run worker:status
# Check hooks are installed
bun run cursor:status
```
Open http://localhost:37777 to see the memory viewer.
## Available Gemini Models
| Model | Free Tier RPM | Notes |
|-------|---------------|-------|
| `gemini-2.5-flash-lite` | 10 (4,000 with billing) | **Default.** Fastest, highest free tier RPM |
| `gemini-2.5-flash` | 5 (1,000 with billing) | Higher capability |
| `gemini-3-flash-preview` | 5 (1,000 with billing) | Latest model |
To change the model, update your settings:
```json
{
"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "your-key",
"CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash"
}
```
## Rate Limiting
Claude-mem automatically handles rate limiting for free tier usage:
- Requests are spaced to stay within limits
- Processing may be slightly slower but stays within quota
- No errors or lost observations
**To remove rate limiting:** Enable billing on your Google Cloud project, then add to settings:
```json
{
"CLAUDE_MEM_GEMINI_BILLING_ENABLED": true
}
```
You'll still use the free quota but with much higher rate limits.
## Troubleshooting
### "Gemini API key not configured"
Ensure your settings file exists and has the correct format:
```bash
cat ~/.claude-mem/settings.json
```
Should output something like:
```json
{
"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "AIza..."
}
```
### Rate limit errors (HTTP 429)
You're exceeding the free tier limits. Options:
1. Wait a few minutes for the rate limit to reset
2. Enable billing on Google Cloud to unlock higher limits
3. Switch to OpenRouter for higher volume needs
### API key invalid
1. Verify your key at [Google AI Studio](https://aistudio.google.com/apikey)
2. Ensure there are no extra spaces or newlines in your settings.json
3. Try generating a new API key
### Worker not processing observations
Check the worker logs:
```bash
bun run worker:logs
```
Look for error messages related to Gemini API calls.
## Switching Providers Later
You can switch between Gemini, OpenRouter, and Claude SDK at any time by updating your settings. No restart required - changes take effect on the next observation.
```json
{
"CLAUDE_MEM_PROVIDER": "openrouter"
}
```
## Next Steps
- [Cursor Integration Overview](/cursor/index) - All Cursor features
- [OpenRouter Setup](/cursor/openrouter-setup) - Alternative provider with 100+ models
- [Configuration Reference](../configuration) - All settings options

180
.agent/services/claude-mem/docs/public/cursor/index.mdx Normal file
View File

@@ -0,0 +1,180 @@
---
title: "Cursor Integration"
description: "Persistent AI memory for Cursor IDE - free tier options available"
---
# Cursor Integration
> **Your AI stops forgetting. Give Cursor persistent memory.**
Every Cursor session starts fresh - your AI doesn't remember what it worked on yesterday. Claude-mem changes that. Your agent builds cumulative knowledge about your codebase, decisions, and patterns over time.
<CardGroup cols={2}>
<Card title="Free to Start" icon="dollar-sign">
Works with Gemini's free tier (1500 req/day) - no subscription required
</Card>
<Card title="Automatic Capture" icon="bolt">
MCP tools, shell commands, and file edits logged without effort
</Card>
<Card title="Smart Context" icon="brain">
Relevant history injected into every chat session
</Card>
<Card title="Works Everywhere" icon="check">
With or without Claude Code subscription
</Card>
</CardGroup>
<Info>
**No Claude Code subscription required.** Use Gemini (free tier) or OpenRouter as your AI provider.
</Info>
## How It Works
Claude-mem integrates with Cursor through native hooks:
1. **Session hooks** capture tool usage, file edits, and shell commands
2. **AI extraction** compresses observations into semantic summaries
3. **Context injection** loads relevant history into each new session
4. **Memory viewer** at http://localhost:37777 shows your knowledge base
## Installation Paths
Choose the installation method that fits your setup:
### Path A: Cursor-Only Users (No Claude Code)
If you're using Cursor without a Claude Code subscription:
```bash
# Clone and build
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem && bun install && bun run build
# Run interactive setup wizard
bun run cursor:setup
```
The setup wizard will:
- Detect you don't have Claude Code
- Help you choose and configure a free AI provider (Gemini recommended)
- Install hooks automatically
- Start the worker service
**Detailed guides:**
- [Gemini Setup](/cursor/gemini-setup) - Recommended free option (1500 req/day)
- [OpenRouter Setup](/cursor/openrouter-setup) - 100+ models including free options
### Path B: Claude Code Users
If you have Claude Code installed:
```bash
# Install the plugin (if not already)
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
# Install Cursor hooks
claude-mem cursor install
```
The plugin uses Claude's SDK by default but you can switch to Gemini or OpenRouter anytime.
## Prerequisites
<AccordionGroup>
<Accordion title="macOS">
- [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
- Cursor IDE
- jq and curl: `brew install jq curl`
</Accordion>
<Accordion title="Linux">
- [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
- Cursor IDE
- jq and curl: `apt install jq curl` or `dnf install jq curl`
</Accordion>
<Accordion title="Windows">
- [Bun](https://bun.sh): `powershell -c "irm bun.sh/install.ps1 | iex"`
- Cursor IDE
- PowerShell 5.1+ (included in Windows 10/11)
- Git for Windows
</Accordion>
</AccordionGroup>
## Quick Commands Reference
After installation, these commands are available from the claude-mem directory:
| Command | Description |
|---------|-------------|
| `bun run cursor:setup` | Interactive setup wizard |
| `bun run cursor:install` | Install Cursor hooks |
| `bun run cursor:uninstall` | Remove Cursor hooks |
| `bun run cursor:status` | Check hook installation status |
| `bun run worker:start` | Start the worker service |
| `bun run worker:stop` | Stop the worker service |
| `bun run worker:status` | Check worker status |
## Verifying Installation
After setup, verify everything is working:
1. **Check worker status:**
```bash
bun run worker:status
```
2. **Check hook installation:**
```bash
bun run cursor:status
```
3. **Open the memory viewer:**
Open http://localhost:37777 in your browser
4. **Restart Cursor** and start a coding session - you should see context being captured
## Provider Comparison
| Provider | Cost | Rate Limit | Best For |
|----------|------|------------|----------|
| Gemini | Free tier | 1500 req/day | Individual use, getting started |
| OpenRouter | Pay-per-use + free models | Varies by model | Model variety, high volume |
| Claude SDK | Included with Claude Code | Unlimited | Claude Code subscribers |
<Tip>
**Recommendation:** Start with Gemini's free tier. It handles typical individual usage well. Switch to OpenRouter or Claude SDK if you need higher limits.
</Tip>
## Troubleshooting
### Worker not starting
```bash
# Check if port is in use
lsof -i :37777
# Force restart
bun run worker:stop && bun run worker:start
# Check logs
bun run worker:logs
```
### Hooks not firing
1. Restart Cursor IDE after installation
2. Check hooks are installed: `bun run cursor:status`
3. Verify hooks.json exists in `.cursor/` directory
### No context appearing
1. Ensure worker is running: `bun run worker:status`
2. Check that you have observations: visit http://localhost:37777
3. Verify your API key is configured correctly
## Next Steps
- [Gemini Setup Guide](/cursor/gemini-setup) - Detailed free tier setup
- [OpenRouter Setup Guide](/cursor/openrouter-setup) - Configure OpenRouter
- [Configuration Reference](../configuration) - All settings options
- [Troubleshooting](../troubleshooting) - Common issues and solutions

191
.agent/services/claude-mem/docs/public/cursor/openrouter-setup.mdx Normal file
View File

@@ -0,0 +1,191 @@
---
title: "Cursor + OpenRouter Setup"
description: "Use Claude-Mem in Cursor with OpenRouter's 100+ AI models"
---
# Cursor + OpenRouter Setup
This guide walks you through setting up Claude-Mem in Cursor using OpenRouter. OpenRouter provides access to 100+ AI models from various providers, including several free options.
<Info>
**Model variety:** Access Claude, GPT-4, Gemini, Llama, Mistral, and many more through a single API key.
</Info>
## Step 1: Get an OpenRouter API Key
1. Go to [OpenRouter](https://openrouter.ai)
2. Sign up or sign in
3. Navigate to [API Keys](https://openrouter.ai/keys)
4. Click **Create Key**
5. Copy your API key - you'll need it in Step 3
<Tip>
**Free models available:** OpenRouter offers free versions of several models including Gemini Flash and others. Check the [model list](https://openrouter.ai/models?show_free=true) for current free options.
</Tip>
## Step 2: Clone and Build Claude-Mem
```bash
# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# Install dependencies
bun install
# Build the project
bun run build
```
## Step 3: Configure OpenRouter Provider
### Option A: Interactive Setup (Recommended)
Run the setup wizard which guides you through everything:
```bash
bun run cursor:setup
```
When prompted for provider, select **OpenRouter**.
### Option B: Manual Configuration
Create the settings file manually:
```bash
# Create settings directory
mkdir -p ~/.claude-mem
# Create settings file with OpenRouter configuration
cat > ~/.claude-mem/settings.json << 'EOF'
{
"CLAUDE_MEM_PROVIDER": "openrouter",
"CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
}
EOF
```
Replace `YOUR_OPENROUTER_API_KEY` with your actual API key.
Then install hooks and start the worker:
```bash
bun run cursor:install
bun run worker:start
```
## Step 4: Restart Cursor
Close and reopen Cursor IDE for the hooks to take effect.
## Step 5: Verify Installation
```bash
# Check worker is running
bun run worker:status
# Check hooks are installed
bun run cursor:status
```
Open http://localhost:37777 to see the memory viewer.
## Recommended Models
### Free Models
| Model | Provider | Notes |
|-------|----------|-------|
| `google/gemini-2.0-flash-exp:free` | Google | Fast, capable |
| `xiaomi/mimo-v2-flash:free` | Xiaomi | Good general purpose |
### Paid Models (Low Cost)
| Model | Approx. Cost | Notes |
|-------|--------------|-------|
| `anthropic/claude-3-haiku` | ~$0.25/1M tokens | Fast, efficient |
| `google/gemini-flash-1.5` | ~$0.075/1M tokens | Great value |
| `mistralai/mistral-7b-instruct` | ~$0.07/1M tokens | Budget option |
To specify a model, add to your settings:
```json
{
"CLAUDE_MEM_PROVIDER": "openrouter",
"CLAUDE_MEM_OPENROUTER_API_KEY": "your-key",
"CLAUDE_MEM_OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
}
```
## Cost Management
OpenRouter charges per token. To manage costs:
1. **Use free models:** Several high-quality free models are available
2. **Monitor usage:** Check your [OpenRouter dashboard](https://openrouter.ai/activity)
3. **Set spending limits:** Configure limits in OpenRouter settings
<Warning>
**Cost awareness:** Unlike Gemini's free tier, OpenRouter paid models charge per request. Monitor your usage if using paid models.
</Warning>
## Troubleshooting
### "OpenRouter API key not configured"
Ensure your settings file exists with the correct format:
```bash
cat ~/.claude-mem/settings.json
```
Should output something like:
```json
{
"CLAUDE_MEM_PROVIDER": "openrouter",
"CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-..."
}
```
### Model not found
1. Check the model ID is correct at [OpenRouter Models](https://openrouter.ai/models)
2. Some models may require payment - check if you have credits
3. Free models have `:free` suffix in their ID
### Rate limits
OpenRouter rate limits vary by model and your account tier. If you hit limits:
1. Wait briefly and retry
2. Consider upgrading your OpenRouter account tier
3. Switch to a less popular model
### API errors
Check the worker logs for details:
```bash
bun run worker:logs
```
Common issues:
- Invalid API key (regenerate at OpenRouter)
- Insufficient credits for paid models
- Model temporarily unavailable
## Switching Providers Later
You can switch between OpenRouter, Gemini, and Claude SDK at any time by updating your settings. No restart required - changes take effect on the next observation.
```json
{
"CLAUDE_MEM_PROVIDER": "gemini"
}
```
## Next Steps
- [Cursor Integration Overview](/cursor/index) - All Cursor features
- [Gemini Setup](/cursor/gemini-setup) - Alternative free provider
- [Configuration Reference](../configuration) - All settings options

775
.agent/services/claude-mem/docs/public/development.mdx Normal file
View File

@@ -0,0 +1,775 @@
---
title: "Development"
description: "Build from source, run tests, and contribute to Claude-Mem"
---
# Development Guide
## Building from Source
### Prerequisites
- Node.js 18.0.0 or higher
- npm (comes with Node.js)
- Git
### Clone and Build
```bash
# Clone repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# Install dependencies
npm install
# Build all components
npm run build
```
### Build Process
The build process uses esbuild to compile TypeScript:
1. Compiles TypeScript to JavaScript
2. Creates standalone executables for each hook in `plugin/scripts/`
3. Bundles MCP search server to `plugin/scripts/mcp-server.cjs`
4. Bundles worker service to `plugin/scripts/worker-service.cjs`
5. Bundles web viewer UI to `plugin/ui/viewer.html`
**Build Output**:
- Hook executables: `*-hook.js` (ESM format)
- Smart installer: `smart-install.js` (ESM format)
- Worker service: `worker-service.cjs` (CJS format)
- MCP server: `mcp-server.cjs` (CJS format)
- Viewer UI: `viewer.html` (self-contained HTML bundle)
### Build Scripts
```bash
# Build everything
npm run build
# Build only hooks
npm run build:hooks
# The build script is defined in scripts/build-hooks.js
```
## Development Workflow
### 1. Make Changes
Edit TypeScript source files in `src/`:
```
src/
├── hooks/ # Hook implementations (entry points + logic)
├── services/ # Worker service and database
├── servers/ # MCP search server
├── sdk/ # Claude Agent SDK integration
├── shared/ # Shared utilities
├── ui/
│ └── viewer/ # React web viewer UI components
└── utils/ # General utilities
```
### 2. Build
```bash
npm run build
```
### 3. Test
```bash
# Run all tests
npm test
# Test specific file
node --test tests/session-lifecycle.test.ts
# Test context injection
npm run test:context
# Verbose context test
npm run test:context:verbose
```
### 4. Manual Testing
```bash
# Start worker manually
npm run worker:start
# Check worker status
npm run worker:status
# View logs
npm run worker:logs
# Test hooks manually
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js
```
### 5. Iterate
Repeat steps 1-4 until your changes work as expected.
## Viewer UI Development
### Working with the React Viewer
The web viewer UI is a React application built into a self-contained HTML bundle.
**Location**: `src/ui/viewer/`
**Structure**:
```
src/ui/viewer/
├── index.tsx # Entry point
├── App.tsx # Main application component
├── components/ # React components
│ ├── Header.tsx # Header with logo and actions
│ ├── Sidebar.tsx # Project filter sidebar
│ ├── Feed.tsx # Main feed with infinite scroll
│ ├── cards/ # Card components
│ │ ├── ObservationCard.tsx
│ │ ├── PromptCard.tsx
│ │ ├── SummaryCard.tsx
│ │ └── SkeletonCard.tsx
├── hooks/ # Custom React hooks
│ ├── useSSE.ts # Server-Sent Events connection
│ ├── usePagination.ts # Infinite scroll pagination
│ ├── useSettings.ts # Settings persistence
│ └── useStats.ts # Database statistics
├── utils/ # Utilities
│ ├── constants.ts # Constants (API URLs, etc.)
│ ├── formatters.ts # Date/time formatting
│ └── merge.ts # Data merging and deduplication
└── assets/ # Static assets (fonts, logos)
```
### Building Viewer UI
```bash
# Build everything including viewer
npm run build
# The viewer is built to plugin/ui/viewer.html
# It's a self-contained HTML file with inlined JS and CSS
```
### Testing Viewer Changes
1. Make changes to React components in `src/ui/viewer/`
2. Build: `npm run build`
3. Sync to installed plugin: `npm run sync-marketplace`
4. Restart worker: `npm run worker:restart`
5. Refresh browser at http://localhost:37777
**Hot Reload**: Not currently supported. Full rebuild + restart required for changes.
### Adding New Viewer Features
**Example: Adding a new card type**
1. Create component in `src/ui/viewer/components/cards/YourCard.tsx`:
```tsx
import React from 'react';
export interface YourCardProps {
// Your data structure
}
export const YourCard: React.FC<YourCardProps> = ({ ... }) => {
return (
<div className="card">
{/* Your UI */}
</div>
);
};
```
2. Import and use in `Feed.tsx`:
```tsx
import { YourCard } from './cards/YourCard';
// In render logic:
{item.type === 'your_type' && <YourCard {...item} />}
```
3. Update types if needed in `src/ui/viewer/types.ts`
4. Rebuild and test
### Viewer UI Architecture
**Data Flow**:
1. Worker service exposes HTTP + SSE endpoints
2. React app fetches initial data via HTTP (paginated)
3. SSE connection provides real-time updates
4. Custom hooks handle state management and data merging
5. Components render cards based on item type
**Key Patterns**:
- **Infinite Scroll**: `usePagination` hook with Intersection Observer
- **Real-Time Updates**: `useSSE` hook with auto-reconnection
- **Deduplication**: `merge.ts` utilities prevent duplicate items
- **Settings Persistence**: `useSettings` hook with localStorage
- **Theme Support**: CSS variables with light/dark/system themes
## Adding New Features
### Adding a New Hook
1. Create hook implementation in `src/hooks/your-hook.ts`:
```typescript
#!/usr/bin/env node
import { readStdin } from '../shared/stdin';
async function main() {
const input = await readStdin();
// Hook implementation
const result = {
hookSpecificOutput: 'Optional output'
};
console.log(JSON.stringify(result));
}
main().catch(console.error);
```
**Note**: As of v4.3.1, hooks are self-contained files. The shebang will be added automatically by esbuild during the build process.
2. Add to `plugin/hooks/hooks.json`:
```json
{
"YourHook": [{
"hooks": [{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/your-hook.js",
"timeout": 120
}]
}]
}
```
4. Rebuild:
```bash
npm run build
```
### Modifying Database Schema
1. Add migration to `src/services/sqlite/migrations.ts`:
```typescript
export const migration011: Migration = {
version: 11,
up: (db: Database) => {
db.run(`
ALTER TABLE observations ADD COLUMN new_field TEXT;
`);
},
down: (db: Database) => {
// Optional: define rollback
}
};
```
2. Update types in `src/services/sqlite/types.ts`:
```typescript
export interface Observation {
// ... existing fields
new_field?: string;
}
```
3. Update database methods in `src/services/sqlite/SessionStore.ts`:
```typescript
createObservation(obs: Observation) {
// Include new_field in INSERT
}
```
4. Test migration:
```bash
# Backup database first!
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
# Run tests
npm test
```
### Extending SDK Prompts
1. Modify prompts in `src/sdk/prompts.ts`:
```typescript
export function buildObservationPrompt(observation: Observation): string {
return `
<observation>
<!-- Add new XML structure -->
</observation>
`;
}
```
2. Update parser in `src/sdk/parser.ts`:
```typescript
export function parseObservation(xml: string): ParsedObservation {
// Parse new XML fields
}
```
3. Test:
```bash
npm test
```
### Adding MCP Search Tools
1. Add tool definition in `src/servers/mcp-server.ts`:
```typescript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'your_new_tool') {
// Implement tool logic
const results = await search.yourNewSearch(params);
return formatResults(results);
}
});
```
2. Add search method in `src/services/sqlite/SessionSearch.ts`:
```typescript
yourNewSearch(params: YourParams): SearchResult[] {
// Implement FTS5 search
}
```
3. Rebuild and test:
```bash
npm run build
npm test
```
## Testing
### Testing Philosophy
Claude-mem relies on **real-world usage and manual testing** rather than traditional unit tests. The project philosophy prioritizes:
1. **Manual verification** - Testing features in actual Claude Code sessions
2. **Integration testing** - Running the full system end-to-end
3. **Database inspection** - Verifying data correctness via SQLite queries
4. **CLI tools** - Interactive tools for checking system state
5. **Observability** - Comprehensive logging and worker health checks
This approach was chosen because:
- Hook behavior depends heavily on Claude Code's runtime environment
- SDK interactions require real API calls and responses
- SQLite and Bun runtime provide stability guarantees
- Manual testing catches integration issues that unit tests miss
### Manual Testing Workflow
When developing new features:
1. **Build and sync**:
```bash
npm run build
npm run sync-marketplace
npm run worker:restart
```
2. **Test in real session**:
- Start Claude Code
- Trigger the feature you're testing
- Verify expected behavior
3. **Check database state**:
```bash
sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM your_table;"
```
4. **Monitor worker logs**:
```bash
npm run worker:logs
```
5. **Verify queue health** (for recovery features):
```bash
bun scripts/check-pending-queue.ts
```
### Testing Tools
**Health Checks**:
```bash
# Worker status
npm run worker:status
# Queue inspection
curl http://localhost:37777/api/pending-queue
# Database integrity
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
```
**Hook Testing**:
```bash
# Test context hook manually
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js
# Test new hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","prompt":"test"}' | node plugin/scripts/new-hook.js
```
**Data Verification**:
```bash
# Check recent observations
sqlite3 ~/.claude-mem/claude-mem.db "
SELECT id, tool_name, created_at
FROM observations
ORDER BY created_at_epoch DESC
LIMIT 10;
"
# Check summaries
sqlite3 ~/.claude-mem/claude-mem.db "
SELECT id, request, completed
FROM session_summaries
ORDER BY created_at_epoch DESC
LIMIT 5;
"
```
### Recovery Feature Testing
For manual recovery features specifically:
1. **Simulate stuck messages**:
```bash
# Manually create stuck message (for testing only)
sqlite3 ~/.claude-mem/claude-mem.db "
UPDATE pending_messages
SET status = 'processing',
started_processing_at_epoch = strftime('%s', 'now', '-10 minutes') * 1000
WHERE id = 123;
"
```
2. **Test recovery**:
```bash
bun scripts/check-pending-queue.ts
```
3. **Verify results**:
```bash
curl http://localhost:37777/api/pending-queue | jq '.queue'
```
### Regression Testing
Before releasing:
1. **Test all hook triggers**:
- SessionStart: Start new Claude Code session
- UserPromptSubmit: Submit a prompt
- PostToolUse: Use a tool like Read
- Summary: Let session complete
- SessionEnd: Close Claude Code
2. **Test core features**:
- Context injection (recent sessions appear)
- Observation processing (summaries generated)
- MCP search tools (search returns results)
- Viewer UI (loads at http://localhost:37777)
- Manual recovery (stuck messages recovered)
3. **Test edge cases**:
- Worker crash recovery
- Database locks
- Port conflicts
- Large databases
4. **Cross-platform** (if applicable):
- macOS
- Linux
- Windows
## Code Style
### TypeScript Guidelines
- Use TypeScript strict mode
- Define interfaces for all data structures
- Use async/await for asynchronous code
- Handle errors explicitly
- Add JSDoc comments for public APIs
### Formatting
- Follow existing code formatting
- Use 2-space indentation
- Use single quotes for strings
- Add trailing commas in objects/arrays
### Example
```typescript
/**
* Create a new observation in the database
*/
export async function createObservation(
obs: Observation
): Promise<number> {
try {
const result = await db.insert('observations', {
session_id: obs.session_id,
tool_name: obs.tool_name,
// ...
});
return result.id;
} catch (error) {
logger.error('Failed to create observation', error);
throw error;
}
}
```
## Debugging
### Enable Debug Logging
```bash
export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs
```
### Inspect Database
```bash
sqlite3 ~/.claude-mem/claude-mem.db
# View schema
.schema observations
# Query data
SELECT * FROM observations LIMIT 10;
```
### Trace Observations
Use correlation IDs to trace observations through the pipeline:
```bash
sqlite3 ~/.claude-mem/claude-mem.db
SELECT correlation_id, tool_name, created_at
FROM observations
WHERE session_id = 'YOUR_SESSION_ID'
ORDER BY created_at;
```
### Debug Hooks
Run hooks manually with test input:
```bash
# Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js
# Test new hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","prompt":"test"}' | node plugin/scripts/new-hook.js
```
## Publishing
### NPM Publishing
```bash
# Update version in package.json
npm version patch # or minor, or major
# Build
npm run build
# Publish to NPM
npm run release
```
The `release` script:
1. Runs tests
2. Builds all components
3. Publishes to NPM registry
### Creating a Release
1. Update version in `package.json`
2. Update `CHANGELOG.md`
3. Commit changes
4. Create git tag
5. Push to GitHub
6. Publish to NPM
```bash
# Manual version bump:
# 1. Update version in package.json
# 2. Update version in plugin/.claude-plugin/plugin.json
# 3. Update version at top of CLAUDE.md
# 4. Update version badge in README.md
# 5. Run: npm run build && npm run sync-marketplace
# Or use npm version command:
npm version 4.3.2
# Update changelog
# Edit CHANGELOG.md manually
# Commit
git add .
git commit -m "chore: Release v4.3.2"
# Tag
git tag v4.3.2
# Push
git push origin main --tags
# Publish to NPM
npm run release
```
## Contributing
### Contribution Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Write tests
5. Update documentation
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
### Pull Request Guidelines
- **Clear title**: Describe what the PR does
- **Description**: Explain why the change is needed
- **Tests**: Include tests for new features
- **Documentation**: Update docs as needed
- **Changelog**: Add entry to CHANGELOG.md
- **Commits**: Use clear, descriptive commit messages
### Code Review Process
1. Automated tests must pass
2. Code review by maintainer
3. Address feedback
4. Final approval
5. Merge to main
## Development Tools
### Recommended VSCode Extensions
- TypeScript
- ESLint
- Prettier
- SQLite Viewer
### Useful Commands
```bash
# Check TypeScript types
npx tsc --noEmit
# Lint code (if configured)
npm run lint
# Format code (if configured)
npm run format
# Clean build artifacts
rm -rf plugin/scripts/*.js plugin/scripts/*.cjs
```
## Troubleshooting Development
### Build Fails
1. Clean node_modules:
```bash
rm -rf node_modules
npm install
```
2. Check Node.js version:
```bash
node --version # Should be >= 18.0.0
```
3. Check for syntax errors:
```bash
npx tsc --noEmit
```
### Tests Fail
1. Check database:
```bash
rm ~/.claude-mem/claude-mem.db
npm test
```
2. Check worker status:
```bash
npm run worker:status
```
3. View logs:
```bash
npm run worker:logs
```
### Worker Won't Start
1. Kill existing process:
```bash
npm run worker:stop
```
2. Check port:
```bash
lsof -i :37777
```
3. Try custom port:
```bash
export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:start
```
## Next Steps
- [Architecture Overview](architecture/overview) - Understand the system
- [Configuration](configuration) - Customize Claude-Mem
- [Troubleshooting](troubleshooting) - Common issues

148
.agent/services/claude-mem/docs/public/docs.json Normal file
View File

@@ -0,0 +1,148 @@
{
"$schema": "https://mintlify.com/schema.json",
"name": "Claude-Mem",
"description": "Persistent memory compression system that preserves context across Claude Code sessions",
"theme": "mint",
"favicon": "/claude-mem-logomark.webp",
"logo": {
"light": "/claude-mem-logo-for-light-mode.webp",
"dark": "/claude-mem-logo-for-dark-mode.webp",
"href": "https://github.com/thedotmack/claude-mem"
},
"colors": {
"primary": "#3B82F6",
"light": "#EFF6FF",
"dark": "#1E40AF"
},
"navbar": {
"links": [
{
"label": "GitHub",
"href": "https://github.com/thedotmack/claude-mem"
}
],
"primary": {
"type": "button",
"label": "Install",
"href": "https://github.com/thedotmack/claude-mem#quick-start"
}
},
"navigation": {
"groups": [
{
"group": "Get Started",
"icon": "rocket",
"pages": [
"introduction",
"installation",
"usage/getting-started",
"usage/openrouter-provider",
"usage/gemini-provider",
"usage/search-tools",
"usage/claude-desktop",
"usage/private-tags",
"usage/export-import",
"usage/manual-recovery",
"usage/folder-context",
"beta-features",
"endless-mode"
]
},
{
"group": "Cursor Integration",
"icon": "wand-magic-sparkles",
"pages": [
"cursor/index",
"cursor/gemini-setup",
"cursor/openrouter-setup"
]
},
{
"group": "Best Practices",
"icon": "lightbulb",
"pages": [
"context-engineering",
"progressive-disclosure",
"smart-explore-benchmark"
]
},
{
"group": "Configuration & Development",
"icon": "gear",
"pages": [
"configuration",
"modes",
"development",
"troubleshooting",
"platform-integration",
"openclaw-integration"
]
},
{
"group": "Architecture",
"icon": "diagram-project",
"pages": [
"architecture/overview",
"architecture-evolution",
"hooks-architecture",
"architecture/hooks",
"architecture/worker-service",
"architecture/database",
"architecture/search-architecture",
"architecture/pm2-to-bun-migration"
]
}
]
},
"footer": {
"socials": {
"github": "https://github.com/thedotmack/claude-mem"
},
"links": [
{
"header": "Resources",
"items": [
{
"label": "Documentation",
"href": "https://github.com/thedotmack/claude-mem"
},
{
"label": "Issues",
"href": "https://github.com/thedotmack/claude-mem/issues"
}
]
},
{
"header": "Legal",
"items": [
{
"label": "License (AGPL-3.0)",
"href": "https://github.com/thedotmack/claude-mem/blob/main/LICENSE"
}
]
}
]
},
"seo": {
"indexing": "all",
"metatags": {
"og:type": "website",
"og:site_name": "Claude-Mem Documentation",
"og:description": "Persistent memory compression system that preserves context across Claude Code sessions"
}
},
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude",
"cursor"
]
},
"integrations": {
"telemetry": {
"enabled": false
}
}
}

111
.agent/services/claude-mem/docs/public/endless-mode.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: "Endless Mode (Beta)"
description: "Experimental biomimetic memory architecture for extended sessions"
---
# Current State of Endless Mode
## Core Concept
Endless Mode is a **biomimetic memory architecture** that solves Claude's context window exhaustion problem. Instead of keeping full tool outputs in the context window (O(N²) complexity), it:
- Captures compressed observations after each tool use
- Replaces transcripts with low token summaries
- Achieves O(N) linear complexity
- Maintains two-tier memory: working memory (compressed) + archive memory (full transcript on disk, maintained by default claude code functionality)
## Implementation Status
**Status**: FUNCTIONAL BUT EXPERIMENTAL
**Current Branch**: `beta/endless-mode` (ahead of main)
**Recent Activity**:
- Merged main branch changes
- Resolved merge conflicts in save-hook, SessionStore, SessionRoutes
- Updated documentation to remove misleading token reduction claims
- Added important caveats about beta status
## Key Architecture Components
1. **Pre-Tool-Use Hook** - Tracks tool execution start, sends tool_use_id to worker
2. **Save Hook (PostToolUse)** - **CRITICAL**: Blocks until observation is generated (110s timeout), injects compressed observation back into context
3. **SessionManager.waitForNextObservation()** - Event-driven wait mechanism (no polling)
4. **SDKAgent** - Generates observations via Agent SDK, emits completion events
5. **Database** - Added `tool_use_id` column for observation correlation
## Configuration
```json
{
"CLAUDE_MEM_ENDLESS_MODE": "false", // Default: disabled
"CLAUDE_MEM_ENDLESS_WAIT_TIMEOUT_MS": "90000" // 90 second timeout
}
```
**Enable via**: Manual checkout of beta branch (see instructions below)
## Flow
```
Tool Executes → Pre-Hook (track ID) → Tool Completes →
Save-Hook (BLOCKS) → Worker processes → SDK generates observation →
Event fired → Hook receives observation → Injects markdown →
Clears input → Context reduced
```
## Known Limitations
From the documentation:
- ⚠️ **Slower than standard mode** - Blocking adds latency
- ⚠️ **Still in development** - May have bugs
- ⚠️ **Not battle-tested** - New architecture
- ⚠️ **Theoretical projections** - Efficiency gains not yet validated in production
## What's Working
- ✅ Synchronous observation injection
- ✅ Event-driven wait mechanism
- ✅ Token reduction via input clearing
- ✅ Database schema with tool_use_id
- ✅ Web UI for version switching
- ✅ Graceful timeout fallbacks
## What's Not Ready
- ❌ Production validation of token savings
- ❌ Comprehensive test coverage
- ❌ Stable channel release
- ❌ Performance benchmarks
- ❌ Long-running session data
## How to Try Endless Mode
Endless Mode is currently only available on the beta branch. To try it:
```bash
# Navigate to your claude-mem installation
cd ~/.claude/plugins/marketplaces/thedotmack/
# Checkout the beta branch
git checkout beta/endless-mode
# Install dependencies
npm install
# Restart the worker
npm run worker:restart
```
**To return to stable:**
```bash
cd ~/.claude/plugins/marketplaces/thedotmack/
git checkout main
npm install
npm run worker:restart
```
## Summary
The implementation is architecturally complete and functional, but remains experimental pending production validation of the theoretical efficiency gains.

811
.agent/services/claude-mem/docs/public/hooks-architecture.mdx Normal file
View File

@@ -0,0 +1,811 @@
# How Claude-Mem Uses Hooks: A Lifecycle-Driven Architecture
## Core Principle
**Observe the main Claude Code session from the outside, process observations in the background, inject context at the right time.**
---
## The Big Picture
Claude-Mem is fundamentally a **hook-driven system**. Every piece of functionality happens in response to lifecycle events:
```
┌─────────────────────────────────────────────────────────┐
│ CLAUDE CODE SESSION │
│ (Main session - user interacting with Claude) │
│ │
│ SessionStart → UserPromptSubmit → Tool Use → Stop │
│ ↓ ↓ ↓ ↓ ↓ ↓ │
│ [3 Hooks] [Hook] [Hook] [Hook] │
└─────────────────────────────────────────────────────────┘
↓ ↓ ↓ ↓ ↓ ↓
┌─────────────────────────────────────────────────────────┐
│ CLAUDE-MEM SYSTEM │
│ │
│ Smart Worker Context New Obs │
│ Install Start Inject Session Capture │
└─────────────────────────────────────────────────────────┘
```
<Note>
As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
</Note>
**Key insight:** Claude-Mem doesn't interrupt or modify Claude Code's behavior. It observes from the outside and provides value through lifecycle hooks.
---
## Why Hooks?
### The Non-Invasive Requirement
Claude-Mem had several architectural constraints:
1. **Can't modify Claude Code**: It's a closed-source binary
2. **Must be fast**: Can't slow down the main session
3. **Must be reliable**: Can't break Claude Code if it fails
4. **Must be portable**: Works on any project without configuration
**Solution:** External command hooks configured via settings.json
### The Hook System Advantage
Claude Code's hook system provides exactly what we need:
<CardGroup cols={2}>
<Card title="Lifecycle Events" icon="clock">
SessionStart, UserPromptSubmit, PostToolUse, Stop
</Card>
<Card title="Non-Blocking" icon="forward">
Hooks run in parallel, don't wait for completion
</Card>
<Card title="Context Injection" icon="upload">
SessionStart and UserPromptSubmit can add context
</Card>
<Card title="Tool Observation" icon="eye">
PostToolUse sees all tool inputs and outputs
</Card>
</CardGroup>
---
## The Hook Scripts
Claude-Mem uses lifecycle hook scripts across 5 lifecycle events. SessionStart runs 3 hooks in sequence: smart-install, worker-service start, and context-hook.
### Pre-Hook: Smart Install (Before SessionStart)
**Purpose:** Intelligently manage dependencies and start worker service
**Note:** This is NOT a lifecycle hook - it's a pre-hook script executed via command chaining before context-hook runs.
**When:** Claude Code starts (startup, clear, or compact)
**What it does:**
1. Checks if dependencies need installation (version marker)
2. Only runs `npm install` when necessary:
- First-time installation
- Version changed in package.json
3. Provides Windows-specific error messages
4. Starts Bun worker service
**Configuration:**
```json
{
"hooks": {
"SessionStart": [{
"matcher": "startup|clear|compact",
"hooks": [{
"type": "command",
"command": "node \"${CLAUDE_PLUGIN_ROOT}/../scripts/smart-install.js\" && node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
"timeout": 300
}]
}]
}
}
```
**Key Features:**
- ✅ Version caching (`.install-version` file)
- ✅ Fast when already installed (~10ms vs 2-5 seconds)
- ✅ Cross-platform compatible
- ✅ Helpful Windows error messages for build tools
**v5.0.3 Enhancement:** Smart caching eliminates redundant installs
**Source:** `scripts/smart-install.js`
---
### Hook 1: SessionStart - Context Injection
**Purpose:** Inject relevant context from previous sessions
**When:** Claude Code starts (runs after smart-install pre-hook)
**What it does:**
1. Extracts project name from current working directory
2. Queries SQLite for recent session summaries (last 10)
3. Queries SQLite for recent observations (configurable, default 50)
4. Formats as progressive disclosure index
5. Outputs to stdout (automatically injected into context)
**Key decisions:**
- ✅ Runs on startup, clear, and compact
- ✅ 300-second timeout (allows for npm install if needed)
- ✅ Progressive disclosure format (index, not full details)
- ✅ Configurable observation count via `CLAUDE_MEM_CONTEXT_OBSERVATIONS`
**Output format:**
```markdown
# [claude-mem] recent context
**Legend:** 🎯 session-request | 🔴 gotcha | 🟡 problem-solution ...
### Oct 26, 2025
**General**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file empty | ~51 |
*Use MCP search tools to access full details*
```
**Source:** `src/hooks/context-hook.ts` → `plugin/scripts/context-hook.js`
---
### Hook 2: UserPromptSubmit (New Session Hook)
**Purpose:** Initialize session tracking when user submits a prompt
**When:** Before Claude processes the user's message
**What it does:**
1. Reads user prompt and session ID from stdin
2. Creates new session record in SQLite
3. Saves raw user prompt for full-text search (v4.2.0+)
4. Starts Bun worker service if not running
5. Returns immediately (non-blocking)
**Configuration:**
```json
{
"hooks": {
"UserPromptSubmit": [{
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js"
}]
}]
}
}
```
**Key decisions:**
- ✅ No matcher (runs for all prompts)
- ✅ Creates session record immediately
- ✅ Stores raw prompts for search (privacy note: local SQLite only)
- ✅ Auto-starts worker service
- ✅ Suppresses output (`suppressOutput: true`)
**Database operations:**
```sql
INSERT INTO sdk_sessions (claude_session_id, project, user_prompt, ...)
VALUES (?, ?, ?, ...)
INSERT INTO user_prompts (session_id, prompt, prompt_number, ...)
VALUES (?, ?, ?, ...)
```
**Source:** `src/hooks/new-hook.ts` → `plugin/scripts/new-hook.js`
---
### Hook 3: PostToolUse (Save Observation Hook)
**Purpose:** Capture tool execution observations for later processing
**When:** Immediately after any tool completes successfully
**What it does:**
1. Receives tool name, input, output from stdin
2. Finds active session for current project
3. Enqueues observation in observation_queue table
4. Returns immediately (processing happens in worker)
**Configuration:**
```json
{
"hooks": {
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js"
}]
}]
}
}
```
**Key decisions:**
- ✅ Matcher: `*` (captures all tools)
- ✅ Non-blocking (just enqueues, doesn't process)
- ✅ Worker processes observations asynchronously
- ✅ Parallel execution safe (each hook gets own stdin)
**Database operations:**
```sql
INSERT INTO observation_queue (session_id, tool_name, tool_input, tool_output, ...)
VALUES (?, ?, ?, ?, ...)
```
**What gets queued:**
```json
{
"session_id": "abc123",
"tool_name": "Edit",
"tool_input": {
"file_path": "/path/to/file.ts",
"old_string": "...",
"new_string": "..."
},
"tool_output": {
"success": true,
"linesChanged": 5
},
"created_at_epoch": 1698765432
}
```
**Source:** `src/hooks/save-hook.ts` → `plugin/scripts/save-hook.js`
---
### Hook 4: Stop Hook (Summary Generation)
**Purpose:** Generate AI-powered session summaries during the session
**When:** When Claude stops (triggered by Stop lifecycle event)
**What it does:**
1. Gathers session observations from database
2. Sends to Claude Agent SDK for summarization
3. Processes response and extracts structured summary
4. Stores in session_summaries table
**Configuration:**
```json
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js"
}]
}]
}
}
```
**Key decisions:**
- ✅ Triggered by Stop lifecycle event
- ✅ Multiple summaries per session (v4.2.0+)
- ✅ Summaries are checkpoints, not endings
- ✅ Uses Claude Agent SDK for AI compression
**Summary structure:**
```xml
<summary>
<request>User's original request</request>
<investigated>What was examined</investigated>
<learned>Key discoveries</learned>
<completed>Work finished</completed>
<next_steps>Remaining tasks</next_steps>
<files_read>
<file>path/to/file1.ts</file>
<file>path/to/file2.ts</file>
</files_read>
<files_modified>
<file>path/to/file3.ts</file>
</files_modified>
<notes>Additional context</notes>
</summary>
```
**Source:** `src/hooks/summary-hook.ts` → `plugin/scripts/summary-hook.js`
---
### Hook 5: SessionEnd (Cleanup Hook)
**Purpose:** Mark sessions as completed when they end
**When:** Claude Code session ends (not on `/clear`)
**What it does:**
1. Marks session as completed in database
2. Allows worker to finish processing
3. Performs graceful cleanup
**Configuration:**
```json
{
"hooks": {
"SessionEnd": [{
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js"
}]
}]
}
}
```
**Key decisions:**
- ✅ Graceful completion (v4.1.0+)
- ✅ No longer sends DELETE to workers
- ✅ Skips cleanup on `/clear` commands
- ✅ Preserves ongoing sessions
**Why graceful cleanup?**
**Old approach (v3):**
```typescript
// ❌ Aggressive cleanup
SessionEnd → DELETE /worker/session → Worker stops immediately
```
**Problems:**
- Interrupted summary generation
- Lost pending observations
- Race conditions
**New approach (v4.1.0+):**
```typescript
// ✅ Graceful completion
SessionEnd → UPDATE sessions SET completed_at = NOW()
Worker sees completion → Finishes processing → Exits naturally
```
**Benefits:**
- Worker finishes important operations
- Summaries complete successfully
- Clean state transitions
**Source:** `src/hooks/cleanup-hook.ts` → `plugin/scripts/cleanup-hook.js`
---
## Hook Execution Flow
### Session Lifecycle
```mermaid
sequenceDiagram
participant User
participant Claude
participant Hooks
participant Worker
participant DB
User->>Claude: Start Claude Code
Claude->>Hooks: SessionStart hook
Hooks->>DB: Query recent context
DB-->>Hooks: Session summaries + observations
Hooks-->>Claude: Inject context
Note over Claude: Context available for session
User->>Claude: Submit prompt
Claude->>Hooks: UserPromptSubmit hook
Hooks->>DB: Create session record
Hooks->>Worker: Start worker (if not running)
Worker-->>DB: Ready to process
Claude->>Claude: Execute tools
Claude->>Hooks: PostToolUse (multiple times)
Hooks->>DB: Queue observations
Note over Worker: Polls queue, processes observations
Worker->>Worker: AI compression
Worker->>DB: Store compressed observations
Worker->>Hooks: Trigger summary hook
Hooks->>DB: Store session summary
User->>Claude: Finish
Claude->>Hooks: SessionEnd hook
Hooks->>DB: Mark session complete
Worker->>DB: Check completion
Worker->>Worker: Finish processing
Worker->>Worker: Exit gracefully
```
### Hook Timing
| Event | Timing | Blocking | Timeout | Output Handling |
|-------|--------|----------|---------|-----------------|
| **SessionStart (smart-install)** | Before session | No | 300s | stderr (log only) |
| **SessionStart (worker-start)** | Before session | No | 60s | stderr (log only) |
| **SessionStart (context)** | Before session | No | 60s | JSON → additionalContext (silent) |
| **UserPromptSubmit** | Before processing | No | 60s | stdout → context |
| **PostToolUse** | After tool | No | 120s | Transcript only |
| **Summary** | Worker triggered | No | 120s | Database |
| **SessionEnd** | On exit | No | 120s | Log only |
<Note>
As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
</Note>
---
## The Worker Service Architecture
### Why a Background Worker?
**Problem:** Hooks must be fast (< 1 second)
**Reality:** AI compression takes 5-30 seconds per observation
**Solution:** Hooks enqueue observations, worker processes async
```
┌─────────────────────────────────────────────────────────┐
│ HOOK (Fast) │
│ 1. Read stdin (< 1ms) │
│ 2. Insert into queue (< 10ms) │
│ 3. Return success (< 20ms total) │
└─────────────────────────────────────────────────────────┘
↓ (queue)
┌─────────────────────────────────────────────────────────┐
│ WORKER (Slow) │
│ 1. Poll queue every 1s │
│ 2. Process observation via Claude SDK (5-30s) │
│ 3. Parse and store results │
│ 4. Mark observation processed │
└─────────────────────────────────────────────────────────┘
```
### Bun Process Management
**Technology:** Bun (JavaScript runtime and process manager)
**Why Bun:**
- Auto-restart on failure
- Fast startup and low memory footprint
- Built-in TypeScript support
- Cross-platform (works on macOS, Linux, Windows)
- No separate process manager needed
**Worker lifecycle:**
```bash
# Started by hooks automatically (if not running)
npm run worker:start
# Status check
npm run worker:status
# View logs
npm run worker:logs
# Restart
npm run worker:restart
# Stop
npm run worker:stop
```
### Worker HTTP API
**Technology:** Express.js REST API on port 37777
**Endpoints:**
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/health` | GET | Health check |
| `/sessions` | POST | Create session |
| `/sessions/:id` | GET | Get session status |
| `/sessions/:id` | PATCH | Update session |
| `/observations` | POST | Enqueue observation |
| `/observations/:id` | GET | Get observation |
**Why HTTP API?**
- Language-agnostic (hooks can be any language)
- Easy debugging (curl commands)
- Standard error handling
- Proper async handling
---
## Design Patterns
### Pattern 1: Fire-and-Forget Hooks
**Principle:** Hooks should return immediately, not wait for completion
```typescript
// ❌ Bad: Hook waits for processing
export async function saveHook(stdin: HookInput) {
const observation = parseInput(stdin);
await processObservation(observation); // BLOCKS!
return success();
}
// ✅ Good: Hook enqueues and returns
export async function saveHook(stdin: HookInput) {
const observation = parseInput(stdin);
await enqueueObservation(observation); // Fast
return success(); // Immediate
}
```
### Pattern 2: Queue-Based Processing
**Principle:** Decouple capture from processing
```
Hook (capture) → Queue (buffer) → Worker (process)
```
**Benefits:**
- Parallel hook execution safe
- Worker failure doesn't affect hooks
- Retry logic centralized
- Backpressure handling
### Pattern 3: Graceful Degradation
**Principle:** Memory system failure shouldn't break Claude Code
```typescript
try {
await captureObservation();
} catch (error) {
// Log error, but don't throw
console.error('Memory capture failed:', error);
return { continue: true, suppressOutput: true };
}
```
**Failure modes:**
- Database locked → Skip observation, log error
- Worker crashed → Auto-restart via Bun
- Network issue → Retry with exponential backoff
- Disk full → Warn user, disable memory
### Pattern 4: Progressive Enhancement
**Principle:** Core functionality works without memory, memory enhances it
```
Without memory: Claude Code works normally
With memory: Claude Code + context from past sessions
Memory broken: Falls back to working normally
```
---
## Hook Debugging
### Debug Mode
Enable detailed hook execution logs:
```bash
claude --debug
```
**Output:**
```
[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js with timeout 60000ms
[DEBUG] Hook command completed with status 0: {"continue":true,"suppressOutput":true}
```
### Common Issues
<AccordionGroup>
<Accordion title="Hook not executing">
**Symptoms:** Hook command never runs
**Debugging:**
1. Check `/hooks` menu - is hook registered?
2. Verify matcher pattern (case-sensitive!)
3. Test command manually: `echo '{}' | node save-hook.js`
4. Check file permissions (executable?)
</Accordion>
<Accordion title="Hook times out">
**Symptoms:** Hook execution exceeds timeout
**Debugging:**
1. Check timeout setting (default 60s)
2. Identify slow operation (database? network?)
3. Move slow operation to worker
4. Increase timeout if necessary
</Accordion>
<Accordion title="Context not injecting">
**Symptoms:** SessionStart hook runs but context missing
**Debugging:**
1. Check stdout (must be valid JSON or plain text)
2. Verify no stderr output (pollutes JSON)
3. Check exit code (must be 0)
4. Look for npm install output (v4.3.1 fix)
</Accordion>
<Accordion title="Observations not captured">
**Symptoms:** PostToolUse hook runs but observations missing
**Debugging:**
1. Check database: `sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observation_queue"`
2. Verify session exists: `SELECT * FROM sdk_sessions`
3. Check worker status: `npm run worker:status`
4. View worker logs: `npm run worker:logs`
</Accordion>
</AccordionGroup>
### Testing Hooks Manually
```bash
# Test context hook
echo '{
"session_id": "test123",
"cwd": "/Users/alex/projects/my-app",
"hook_event_name": "SessionStart",
"source": "startup"
}' | node plugin/scripts/context-hook.js
# Test save hook
echo '{
"session_id": "test123",
"tool_name": "Edit",
"tool_input": {"file_path": "test.ts"},
"tool_output": {"success": true}
}' | node plugin/scripts/save-hook.js
# Test with actual Claude Code
claude --debug
/hooks # View registered hooks
# Submit prompt and watch debug output
```
---
## Performance Considerations
### Hook Execution Time
**Target:** < 100ms per hook
**Actual measurements:**
| Hook | Average | p95 | p99 |
|------|---------|-----|-----|
| SessionStart (smart-install, cached) | 10ms | 20ms | 40ms |
| SessionStart (smart-install, first run) | 2500ms | 5000ms | 8000ms |
| SessionStart (context) | 45ms | 120ms | 250ms |
| SessionStart (user-message) | 5ms | 10ms | 15ms |
| UserPromptSubmit | 12ms | 25ms | 50ms |
| PostToolUse | 8ms | 15ms | 30ms |
| SessionEnd | 5ms | 10ms | 20ms |
**Why smart-install is sometimes slow:**
- First-time: Full npm install (2-5 seconds)
- Cached: Version check only (~10ms)
- Version change: Full npm install + worker restart
**Optimization (v5.0.3):**
- Version caching with `.install-version` marker
- Only install on version change or missing deps
- Windows-specific error messages with build tool help
### Database Performance
**Schema optimizations:**
- Indexes on `project`, `created_at_epoch`, `claude_session_id`
- FTS5 virtual tables for full-text search
- WAL mode for concurrent reads/writes
**Query patterns:**
```sql
-- Fast: Uses index on (project, created_at_epoch)
SELECT * FROM session_summaries
WHERE project = ?
ORDER BY created_at_epoch DESC
LIMIT 10
-- Fast: Uses index on claude_session_id
SELECT * FROM sdk_sessions
WHERE claude_session_id = ?
LIMIT 1
-- Fast: FTS5 full-text search
SELECT * FROM observations_fts
WHERE observations_fts MATCH ?
ORDER BY rank
LIMIT 20
```
### Worker Throughput
**Bottleneck:** Claude API latency (5-30s per observation)
**Mitigation:**
- Process observations sequentially (simpler, more predictable)
- Skip low-value observations (TodoWrite, ListMcpResourcesTool)
- Batch summaries (generate every N observations, not every observation)
**Future optimization:**
- Parallel processing (multiple workers)
- Smart batching (combine related observations)
- Lazy summarization (summarize only when needed)
---
## Security Considerations
### Hook Command Safety
**Risk:** Hooks execute arbitrary commands with user permissions
**Mitigations:**
1. **Frozen at startup:** Hook configuration captured at start, changes require review
2. **User review required:** `/hooks` menu shows changes, requires approval
3. **Plugin isolation:** `${CLAUDE_PLUGIN_ROOT}` prevents path traversal
4. **Input validation:** Hooks validate stdin schema before processing
### Data Privacy
**What gets stored:**
- User prompts (raw text) - v4.2.0+
- Tool inputs and outputs
- File paths read/modified
- Session summaries
**Privacy guarantees:**
- All data stored locally in `~/.claude-mem/claude-mem.db`
- No cloud uploads (API calls only for AI compression)
- SQLite file permissions: user-only read/write
- No analytics or telemetry
### API Key Protection
**Configuration:**
- Anthropic API key in `~/.anthropic/api_key` or `ANTHROPIC_API_KEY` env var
- Worker inherits environment from Claude Code
- Never logged or stored in database
---
## Key Takeaways
1. **Hooks are interfaces**: They define clean boundaries between systems
2. **Non-blocking is critical**: Hooks must return fast, workers do the heavy lifting
3. **Graceful degradation**: Memory system can fail without breaking Claude Code
4. **Queue-based decoupling**: Capture and processing happen independently
5. **Progressive disclosure**: Context injection uses index-first approach
6. **Lifecycle alignment**: Each hook has a clear, single purpose
---
## Further Reading
- [Claude Code Hooks Reference](https://docs.claude.com/claude-code/hooks) - Official documentation
- [Progressive Disclosure](progressive-disclosure) - Context priming philosophy
- [Architecture Evolution](architecture-evolution) - v3 to v4 journey
- [Worker Service Design](architecture/worker-service) - Background processing details
---
*The hook-driven architecture enables Claude-Mem to be both powerful and invisible. Users never notice the memory system working - it just makes Claude smarter over time.*

116
.agent/services/claude-mem/docs/public/installation.mdx Normal file
View File

@@ -0,0 +1,116 @@
---
title: "Installation"
description: "Install Claude-Mem plugin for persistent memory across sessions"
---
# Installation Guide
## Quick Start
Install Claude-Mem directly from the plugin marketplace:
```bash
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```
That's it! The plugin will automatically:
- Download prebuilt binaries (no compilation needed)
- Install all dependencies (including SQLite binaries)
- Configure hooks for session lifecycle management
- Auto-start the worker service on first session
Start a new Claude Code session and you'll see context from previous sessions automatically loaded.
> **Important:** Claude-Mem is published on npm, but running `npm install -g claude-mem` installs the
> **SDK/library only**. It does **not** register plugin hooks or start the worker service.
> To use Claude-Mem as a persistent memory plugin, always install via the `/plugin` commands above.
## System Requirements
- **Node.js**: 18.0.0 or higher
- **Claude Code**: Latest version with plugin support
- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
- **SQLite 3**: For persistent storage (bundled)
## Advanced Installation
For development or testing, you can clone and build from source:
### Clone and Build
```bash
# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# Install dependencies
npm install
# Build hooks and worker service
npm run build
# Worker service will auto-start on first Claude Code session
# Or manually start with:
npm run worker:start
# Verify worker is running
npm run worker:status
```
### Post-Installation Verification
#### 1. Automatic Dependency Installation
Dependencies are installed automatically during plugin installation. The SessionStart hook also ensures dependencies are up-to-date on each session start (this is fast and idempotent). Works cross-platform on Windows, macOS, and Linux.
#### 2. Verify Plugin Installation
Check that hooks are configured in Claude Code:
```bash
cat plugin/hooks/hooks.json
```
#### 3. Data Directory Location
Data is stored in `~/.claude-mem/`:
- Database: `~/.claude-mem/claude-mem.db`
- PID file: `~/.claude-mem/.worker.pid`
- Port file: `~/.claude-mem/.worker.port`
- Logs: `~/.claude-mem/logs/worker-YYYY-MM-DD.log`
- Settings: `~/.claude-mem/settings.json`
Override with environment variable:
```bash
export CLAUDE_MEM_DATA_DIR=/custom/path
```
#### 4. Check Worker Logs
```bash
npm run worker:logs
```
#### 5. Test Context Retrieval
```bash
npm run test:context
```
## Upgrading
Upgrades are automatic when updating via the plugin marketplace. Key changes in recent versions:
**v7.1.0**: PM2 replaced with native Bun process management. Migration is automatic on first hook trigger.
**v7.0.0+**: 11 configuration settings, dual-tag privacy system.
**v5.4.0+**: Skill-based search replaces MCP tools, saving ~2,250 tokens per session.
See [CHANGELOG](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md) for complete version history.
## Next Steps
- [Getting Started Guide](usage/getting-started) - Learn how Claude-Mem works automatically
- [MCP Search Tools](usage/search-tools) - Query your project history
- [Configuration](configuration) - Customize Claude-Mem behavior

112
.agent/services/claude-mem/docs/public/introduction.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: "Introduction"
description: "Persistent memory compression system for Claude Code"
---
# Claude-Mem
**Persistent memory compression system for Claude Code**
Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.
## Quick Start
Start a new Claude Code session in the terminal and enter the following commands:
```bash
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```
Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
## Key Features
- 🧠 **Persistent Memory** - Context survives across sessions
- 📁 **Folder Context Files** - Auto-generated `CLAUDE.md` in project folders with activity timelines
- 🌐 **Multilingual Modes** - Supports 28 languages (Spanish, Chinese, French, Japanese, etc.)
- 🎭 **Mode System** - Switch between workflows (Code, Email Investigation, Chill)
- 🔍 **MCP Search Tools** - Query your project history with natural language
- 🌐 **Web Viewer UI** - Real-time memory stream visualization at http://localhost:37777
- 🔒 **Privacy Control** - Use `<private>` tags to exclude sensitive content from storage
- ⚙️ **Context Configuration** - Fine-grained control over what context gets injected
- 🤖 **Automatic Operation** - No manual intervention required
- 📊 **FTS5 Search** - Fast full-text search across observations
- 🔗 **Citations** - Reference past observations with IDs
## How It Works
```
┌─────────────────────────────────────────────────────────────┐
│ Session Start → Inject context from last 10 sessions │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ User Prompts → Create session, save user prompts │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Tool Executions → Capture observations (Read, Write, etc.) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Worker Processes → Extract learnings via Claude Agent SDK │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Session Ends → Generate summary, ready for next session │
└─────────────────────────────────────────────────────────────┘
```
**Core Components:**
1. **4 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop
2. **Smart Install** - Cached dependency checker (pre-hook script)
3. **Worker Service** - HTTP API on port 37777 managed by Bun
4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
5. **MCP Search Tools** - Query historical context with natural language
6. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll
See [Architecture Overview](architecture/overview) for details.
## System Requirements
- **Node.js**: 18.0.0 or higher
- **Claude Code**: Latest version with plugin support
- **Bun**: JavaScript runtime and process manager (auto-installed if missing)
- **SQLite 3**: For persistent storage (bundled)
## What's New
**v9.0.0 - Live Context:**
- **Folder Context Files**: Auto-generated `CLAUDE.md` in project folders with activity timelines
- **Worktree Support**: Unified context from parent repos and git worktrees
- **Configurable Observation Limits**: Control how many observations appear in context
- **Windows Fixes**: Resolved IPC detection and hook execution issues
- **Settings Auto-Creation**: `settings.json` now auto-creates on first run
- **MCP Tools Naming**: Updated from "mem-search skill" to "MCP tools" terminology
**v7.1.0 - Bun Migration:**
- Replaced PM2 with native Bun process management
- Switched from better-sqlite3 to bun:sqlite for faster database access
- Simplified cross-platform support
**v7.0.0 - Context Configuration:**
- 11 settings for fine-grained control over context injection
- Dual-tag privacy system (`<private>` tags)
## Next Steps
<CardGroup cols={2}>
<Card title="Installation" icon="download" href="/installation">
Quick start & advanced installation
</Card>
<Card title="Getting Started" icon="rocket" href="/usage/getting-started">
Learn how Claude-Mem works automatically
</Card>
<Card title="Folder Context" icon="folder-open" href="/usage/folder-context">
Auto-generated folder CLAUDE.md files
</Card>
<Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
Query your project history
</Card>
</CardGroup>

104
.agent/services/claude-mem/docs/public/modes.mdx Normal file
View File

@@ -0,0 +1,104 @@
---
title: "Modes & Languages"
description: "Configure Claude-Mem behavior and language with the Mode System"
---
# Modes & Languages
Claude-Mem uses a flexible **Mode System** to adapt its behavior, observation types, and output language. This allows you to switch between different workflows (like coding vs. email investigation) or languages without reinstalling the plugin.
## What is a Mode?
A "mode" is a configuration profile that defines:
1. **Observer Role**: How Claude should analyze your work (e.g., "Software Engineer" vs. "Forensic Analyst").
2. **Observation Types**: Valid categories for memory (e.g., "Bug Fix", "Feature" vs. "Person", "Organization").
3. **Concepts**: Semantic tags for indexing (e.g., "Pattern", "Trade-off").
4. **Language**: The language used for generating observations and summaries.
## Configuration
Set the active mode using the `CLAUDE_MEM_MODE` setting in `~/.claude-mem/settings.json`:
```json
{
"CLAUDE_MEM_MODE": "code--es"
}
```
Or via environment variable:
```bash
export CLAUDE_MEM_MODE="code--fr"
```
## Available Modes
### Code Mode (Default)
The standard mode for software development. Captures bug fixes, features, refactors, and architectural decisions.
**ID:** `code`
### Code Mode Variants
Behavioral variants that change how the code mode operates:
| Variant | Mode ID | Description |
|---------|---------|-------------|
| **Chill** | `code--chill` | Produces fewer observations. Only records things "painful to rediscover" - shipped features, architectural decisions, and non-obvious gotchas. Skips routine work and obvious changes. |
### Multilingual Code Modes
Inherits all behavior from Code Mode but instructs Claude to generate **all** memory artifacts (titles, narratives, facts, summaries) in the target language.
| Language | Mode ID | Native Name |
|----------|---------|-------------|
| **Arabic** | `code--ar` | العربية |
| **Bengali** | `code--bn` | বাংলা |
| **Chinese** | `code--zh` | 中文 |
| **Czech** | `code--cs` | Čeština |
| **Danish** | `code--da` | Dansk |
| **Dutch** | `code--nl` | Nederlands |
| **Finnish** | `code--fi` | Suomi |
| **French** | `code--fr` | Français |
| **German** | `code--de` | Deutsch |
| **Greek** | `code--el` | Ελληνικά |
| **Hebrew** | `code--he` | עברית |
| **Hindi** | `code--hi` | हिन्दी |
| **Hungarian** | `code--hu` | Magyar |
| **Indonesian** | `code--id` | Bahasa Indonesia |
| **Urdu** | `code--ur` | اردو |
| **Italian** | `code--it` | Italiano |
| **Japanese** | `code--ja` | 日本語 |
| **Korean** | `code--ko` | 한국어 |
| **Norwegian** | `code--no` | Norsk |
| **Polish** | `code--pl` | Polski |
| **Portuguese (Brazil)** | `code--pt-br` | Português Brasileiro |
| **Romanian** | `code--ro` | Română |
| **Russian** | `code--ru` | Русский |
| **Spanish** | `code--es` | Español |
| **Swedish** | `code--sv` | Svenska |
| **Thai** | `code--th` | ภาษาไทย |
| **Turkish** | `code--tr` | Türkçe |
| **Ukrainian** | `code--uk` | Українська |
| **Vietnamese** | `code--vi` | Tiếng Việt |
### Email Investigation Mode
A specialized mode for analyzing email dumps (e.g., FOIA releases, corporate archives). Focuses on identifying entities, relationships, timeline events, and key topics.
**ID:** `email-investigation`
**Observation Types:**
- `entity`: Person, organization, or email address
- `relationship`: Connection between entities
- `timeline-event`: Time-stamped event in communication sequence
- `evidence`: Supporting documentation or proof
- `anomaly`: Suspicious pattern or irregularity
- `conclusion`: Investigative finding or determination
## Mode Inheritance
The system supports inheritance using the `--` separator. For example, `code--es` means:
1. Load `code` (Parent) configuration.
2. Load `code--es` (Child) configuration.
3. Merge Child into Parent (Child overrides).
This allows for lightweight "remix" modes that only change specific aspects (like the language prompt) while keeping the core definitions intact.

381
.agent/services/claude-mem/docs/public/openclaw-integration.mdx Normal file
View File

@@ -0,0 +1,381 @@
---
title: OpenClaw Integration
description: Persistent memory for OpenClaw agents — observation recording, system prompt context injection, and real-time observation feeds
icon: dragon
---
## Overview
The OpenClaw plugin gives claude-mem persistent memory to agents running on the [OpenClaw](https://openclaw.ai) gateway. It handles three things:
1. **Observation recording** — Captures tool usage from OpenClaw's embedded runner and sends it to the claude-mem worker for AI processing
2. **System prompt context injection** — Injects the observation timeline into each agent's system prompt via the `before_prompt_build` hook, keeping `MEMORY.md` free for agent-curated memory
3. **Observation feed** — Streams new observations to messaging channels (Telegram, Discord, Slack, etc.) in real-time via SSE
<Info>
OpenClaw's embedded runner (`pi-embedded`) calls the Anthropic API directly without spawning a `claude` process, so claude-mem's standard hooks never fire. This plugin bridges that gap by using OpenClaw's event system to capture the same data.
</Info>
## How It Works
```plaintext
OpenClaw Gateway
│
├── before_agent_start ───→ Init session
├── before_prompt_build ──→ Inject context into system prompt
├── tool_result_persist ──→ Record observation
├── agent_end ────────────→ Summarize + Complete session
└── gateway_start ────────→ Reset session tracking + context cache
│
▼
Claude-Mem Worker (localhost:37777)
├── POST /api/sessions/init
├── POST /api/sessions/observations
├── POST /api/sessions/summarize
├── POST /api/sessions/complete
├── GET /api/context/inject ──→ System prompt context
└── GET /stream ─────────────→ SSE → Messaging channels
```
### Event Lifecycle
<Steps>
<Step title="Agent starts (before_agent_start)">
When an OpenClaw agent starts, the plugin initializes a session by sending the user prompt to `POST /api/sessions/init` so the worker can create a new session and start processing.
</Step>
<Step title="Context injected (before_prompt_build)">
Before each LLM call, the plugin fetches the observation timeline from the worker's `/api/context/inject` endpoint and returns it as `appendSystemContext`. This injects cross-session context directly into the agent's system prompt without writing any files.
The context is cached for 60 seconds to avoid re-fetching on every LLM turn within a session.
</Step>
<Step title="Tool use recorded (tool_result_persist)">
Every time the agent uses a tool (Read, Write, Bash, etc.), the plugin sends the observation to `POST /api/sessions/observations` with the tool name, input, and truncated response (max 1000 chars). This is fire-and-forget — it doesn't block the agent from continuing work.
Tools prefixed with `memory_` are skipped to avoid recursive recording.
</Step>
<Step title="Agent finishes (agent_end)">
When the agent completes, the plugin extracts the last assistant message and sends it to `POST /api/sessions/summarize`, then calls `POST /api/sessions/complete` to close the session. Both are fire-and-forget.
</Step>
<Step title="Gateway restarts (gateway_start)">
Clears all session tracking (session IDs, context cache) so agents get fresh state after a gateway restart.
</Step>
</Steps>
### System Prompt Context Injection
The plugin injects cross-session observation context into each agent's system prompt via OpenClaw's `before_prompt_build` hook. The content comes from the worker's `GET /api/context/inject?projects=<project>` endpoint, which generates a formatted markdown timeline from the SQLite database.
This approach keeps `MEMORY.md` under the agent's control for curated long-term memory (decisions, preferences, durable facts), while the observation timeline is delivered through the system prompt where it belongs.
<Info>
Context is cached for 60 seconds per project to avoid re-fetching on every LLM turn. The cache is cleared on gateway restart. Use `syncMemoryFileExclude` to opt specific agents out of context injection entirely.
</Info>
### Observation Feed (SSE → Messaging)
The plugin runs a background service that connects to the worker's SSE stream (`GET /stream`) and forwards `new_observation` events to a configured messaging channel. This lets you monitor what your agents are learning in real-time from Telegram, Discord, Slack, or any supported OpenClaw channel.
The SSE connection uses exponential backoff (1s → 30s) for automatic reconnection.
## Setting Up the Observation Feed
The observation feed sends a formatted message to your OpenClaw channel every time claude-mem creates a new observation. Each message includes the observation title and subtitle so you can follow along as your agents work.
Messages look like this in your channel:
```
🧠 Claude-Mem Observation
**Implemented retry logic for API client**
Added exponential backoff with configurable max retries to handle transient failures
```
### Step 1: Choose your channel
The observation feed works with any channel that your OpenClaw gateway has configured. You need two pieces of information:
- **Channel type** — The name of the channel plugin registered with OpenClaw (e.g., `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `line`)
- **Target ID** — The chat ID, channel ID, or user ID where messages should be sent
<AccordionGroup>
<Accordion title="Telegram" icon="telegram">
**Channel type:** `telegram`
**Target ID:** Your Telegram chat ID (numeric). To find it:
1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
2. It will reply with your chat ID (e.g., `123456789`)
3. For group chats, the ID is negative (e.g., `-1001234567890`)
```json
"observationFeed": {
"enabled": true,
"channel": "telegram",
"to": "123456789"
}
```
</Accordion>
<Accordion title="Discord" icon="discord">
**Channel type:** `discord`
**Target ID:** The Discord channel ID. To find it:
1. Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
2. Right-click the channel → Copy Channel ID
```json
"observationFeed": {
"enabled": true,
"channel": "discord",
"to": "1234567890123456789"
}
```
</Accordion>
<Accordion title="Slack" icon="slack">
**Channel type:** `slack`
**Target ID:** The Slack channel ID (not the channel name). To find it:
1. Open the channel in Slack
2. Click the channel name at the top
3. Scroll to the bottom of the channel details — the ID looks like `C01ABC2DEFG`
```json
"observationFeed": {
"enabled": true,
"channel": "slack",
"to": "C01ABC2DEFG"
}
```
</Accordion>
<Accordion title="Signal" icon="signal-messenger">
**Channel type:** `signal`
**Target ID:** The Signal phone number or group ID configured in your OpenClaw gateway.
```json
"observationFeed": {
"enabled": true,
"channel": "signal",
"to": "+1234567890"
}
```
</Accordion>
<Accordion title="WhatsApp" icon="whatsapp">
**Channel type:** `whatsapp`
**Target ID:** The WhatsApp phone number or group JID configured in your OpenClaw gateway.
```json
"observationFeed": {
"enabled": true,
"channel": "whatsapp",
"to": "+1234567890"
}
```
</Accordion>
<Accordion title="LINE" icon="line">
**Channel type:** `line`
**Target ID:** The LINE user ID or group ID from the LINE Developer Console.
```json
"observationFeed": {
"enabled": true,
"channel": "line",
"to": "U1234567890abcdef"
}
```
</Accordion>
</AccordionGroup>
### Step 2: Add the config to your gateway
Add the `observationFeed` block to your claude-mem plugin config in your OpenClaw gateway configuration:
```json
{
"plugins": {
"claude-mem": {
"enabled": true,
"config": {
"project": "my-project",
"observationFeed": {
"enabled": true,
"channel": "telegram",
"to": "123456789"
}
}
}
}
}
```
<Warning>
The `channel` value must match a channel plugin that is already configured and running on your OpenClaw gateway. If the channel isn't registered, you'll see `Unknown channel type: <channel>` in the logs.
</Warning>
### Step 3: Verify the connection
After starting the gateway, check that the feed is connected:
1. **Check the logs** — You should see:
```
[claude-mem] Observation feed starting — channel: telegram, target: 123456789
[claude-mem] Connecting to SSE stream at http://localhost:37777/stream
[claude-mem] Connected to SSE stream
```
2. **Use the status command** — Run `/claude_mem_feed` in any OpenClaw chat to see:
```
Claude-Mem Observation Feed
Enabled: yes
Channel: telegram
Target: 123456789
Connection: connected
```
3. **Trigger a test** — Have an agent do some work. When the worker processes the tool usage into an observation, you'll receive a message in your configured channel.
<Info>
The feed only sends `new_observation` events — not raw tool usage. Observations are generated asynchronously by the worker's AI agent, so there's a 1-2 second delay between tool use and the observation message appearing in your channel.
</Info>
### Troubleshooting the Feed
| Symptom | Cause | Fix |
|---------|-------|-----|
| `Connection: disconnected` | Worker not running or wrong port | Check `workerPort` config, run `npm run worker:status` |
| `Connection: reconnecting` | Worker was running but connection dropped | The plugin auto-reconnects with backoff — wait up to 30s |
| `Unknown channel type` in logs | Channel plugin not loaded on gateway | Verify your OpenClaw gateway has the channel plugin configured |
| No messages appearing | Feed connected but no observations being created | Check that agents are running and the worker is processing observations |
| `Observation feed disabled` in logs | `enabled` is `false` or missing | Set `observationFeed.enabled` to `true` |
| `Observation feed misconfigured` in logs | Missing `channel` or `to` | Both `channel` and `to` are required |
## Installation
Run this one-liner to install everything automatically:
```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```
The installer handles dependency checks (Bun, uv), plugin installation, memory slot configuration, AI provider setup, worker startup, and optional observation feed configuration.
You can also pre-select options:
```bash
# With a specific AI provider
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY
# Fully unattended (defaults to Claude Max Plan)
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive
# Upgrade existing installation
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade
```
### Manual Configuration
Add `claude-mem` to your OpenClaw gateway's plugin configuration:
```json
{
"plugins": {
"claude-mem": {
"enabled": true,
"config": {
"project": "my-project",
"syncMemoryFile": true,
"workerPort": 37777,
"observationFeed": {
"enabled": true,
"channel": "telegram",
"to": "your-chat-id"
}
}
}
}
}
```
<Note>
The claude-mem worker service must be running on the same machine as the OpenClaw gateway. The plugin communicates with it via HTTP on `localhost:37777`.
</Note>
## Configuration
<ParamField body="project" type="string" default="openclaw">
Project name for scoping observations in the memory database. All observations from this gateway will be stored under this project name.
</ParamField>
<ParamField body="syncMemoryFile" type="boolean" default={true}>
Inject observation context into the agent system prompt via `before_prompt_build` hook. When `true`, agents receive cross-session context automatically. Set to `false` to disable context injection entirely (observations are still recorded).
</ParamField>
<ParamField body="syncMemoryFileExclude" type="string[]" default={[]}>
Agent IDs excluded from automatic context injection. Useful for agents that curate their own memory and don't need the observation timeline (e.g., `["snarf", "debugger"]`). Observations are still recorded for excluded agents — only the context injection is skipped.
</ParamField>
<ParamField body="workerPort" type="number" default={37777}>
Port for the claude-mem worker service. Override if your worker runs on a non-default port.
</ParamField>
<ParamField body="observationFeed.enabled" type="boolean" default={false}>
Enable live observation streaming to messaging channels.
</ParamField>
<ParamField body="observationFeed.channel" type="string">
Channel type: `telegram`, `discord`, `signal`, `slack`, `whatsapp`, `line`
</ParamField>
<ParamField body="observationFeed.to" type="string">
Target chat/user/channel ID to send observations to.
</ParamField>
## Commands
### /claude_mem_feed
Show or toggle the observation feed status.
```
/claude_mem_feed # Show current status
/claude_mem_feed on # Request enable
/claude_mem_feed off # Request disable
```
### /claude_mem_status
Check worker health and session status.
```
/claude_mem_status
```
Returns worker status, port, active session count, and observation feed connection state.
## Architecture
The plugin uses HTTP calls to the already-running claude-mem worker service rather than spawning subprocesses. This means:
- No `bun` dependency required on the gateway
- No process spawn overhead per event
- Uses the same worker API that Claude Code hooks use
- All operations are non-blocking (fire-and-forget where possible)
### Session Tracking
Each OpenClaw agent session gets a unique `contentSessionId` (format: `openclaw-<sessionKey>-<timestamp>`) that maps to a claude-mem session in the worker. The plugin tracks:
- `sessionIds` — Maps OpenClaw session keys to content session IDs
- `contextCache` — TTL cache (60s) for context injection responses, keyed by project
Both are cleared on `gateway_start`.
## Requirements
- Claude-mem worker service running on `localhost:37777` (or configured port)
- OpenClaw gateway with plugin support
- Network access between gateway and worker (localhost only)

Some files were not shown because too many files have changed in this diff Show More