jose-compu / jose-compu/claude-code-semantic-memory

Add CLAUDE.md template with session-start /index . instruction

Open
#2 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Summary

Document the recommended `CLAUDE.md` template that consumers of the `semantic-memory` plugin should place at the root of their workspaces. The template enforces an incremental `/index .` at session start and explains the available slash commands and namespaces.

This issue tracks shipping the snippet below as a copy-paste-ready section in the plugin docs (and optionally in `skills/semantic-memory/SKILL.md` / a `templates/CLAUDE.md` reference file) so users get a consistent first-run experience.

## Proposed `CLAUDE.md` snippet

```markdown
# CLAUDE.md

## Semantic Memory (LogosDB)

The **semantic-memory** plugin is active for this workspace. Vector data lives in `.logosdb/` (git-ignored). The plugin provides three slash commands that work without any extra setup.

### Session start — mandatory

**Run `/index .` at the start of every session** before doing other work. This incrementally refreshes the full index (only changed/new files are re-embedded; unchanged files are skipped, so it is fast).

```
/index .
```

### Slash commands

| Command | What it does |
|---------|--------------|
| `/index ` | Index or re-index a file or directory (incremental by default). Use `.` for the whole project, or a subdirectory/file for targeted refresh. |
| `/search ` | Semantic search over indexed content. Returns ranked file matches. Accepts `--top-k=n` (default 5), `--namespace=name` (default `code`), and optional ISO timestamp bounds (`--from-ts`, `--to-ts`). |
| `/forget ` | Delete indexed chunks by semantic query match or by row id. Use to remove stale or unwanted content from the index. |

### Namespaces

- **`code`** (default) — source files and general project content
- Use `--namespace=docs` or `-n docs` for documentation-only searches
- Use `--namespace=decisions` for durable architectural or research notes

### When to re-index

- After pulling / merging changes: `/index .`
- After editing a specific file: `/index `
- Before a broad search when files may have changed since last index

### Opting out of auto-index

If the repo grows very large and `.` is too slow, replace `/index .` in the session-start instruction above with a narrower path (e.g. `/index ./src`) and document that here.
```

## Acceptance criteria

- [ ] `README.md` references the snippet (or links to a `templates/CLAUDE.md`) under the existing `Slash commands` section.
- [ ] `skills/semantic-memory/SKILL.md` mentions the session-start `/index .` contract and points to the template.
- [ ] Verify `/index .` with `incremental: true` is the documented default and matches `logosdb-mcp-server >= 0.7.11` behavior.
- [ ] Note in docs that `.logosdb/` should be git-ignored.

## Notes

- Keeps the contract simple: one mandatory command at session start, three slash commands, three namespaces.
- The opt-out section gives an escape hatch for very large repos without changing plugin defaults.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.