npm package: @septum-jdr/private-context
Description: Enterprise automatic context manager for Claude CLI with SQLite + FTS5
Author: Juan David Reina
Latest version: 2.0.2

# @septum-jdr/private-context

![npm version](https://img.shields.io/npm/v/@septum-jdr/private-context)
![npm downloads](https://img.shields.io/npm/dm/@septum-jdr/private-context)
![license](https://img.shields.io/npm/l/@septum-jdr/private-context)
![node version](https://img.shields.io/node/v/@septum-jdr/private-context)

Persistent semantic memory engine for **Claude CLI** SQLite + FTS5 powered automatic context injection.

---

## ✨ Why This Exists

Claude CLI does not persist long-term context across executions.

`@septum-jdr/private-context` adds:

- Persistent memory
- Automatic context injection
- Semantic + recency ranking
- Zero manual workflow
- Fully automatic execution wrapper

No extra commands. No manual context files.

---

## 🚀 What It Does (Automatically)

Every time you run:

```bash
claude "your prompt"
```

The wrapper:

1. Searches relevant historical entries
2. Combines:

   * Semantic match (FTS5)
   * Recent history
3. Injects context before your prompt
4. Executes `claude-original`
5. Stores prompt + response
6. Auto-prunes old records
7. Displays: `[private-context ACTIVE]`

Completely **automatic**.

---

## 🧠 Search Strategy

Hybrid model:

| Strategy             | Purpose                           |
| -------------------- | --------------------------------- |
| FTS5 Semantic Search | Find conceptually related entries |
| Recency Ranking      | Maintain session continuity       |
| Auto-prune           | Prevent uncontrolled DB growth    |

- No embeddings required.
- No external APIs.
- No recurring costs.

---

## 📦 Installation

```
npm install -g @septum-jdr/private-context
```

Requires:

* Node 18+
* Claude CLI installed

Recommended:

* Node 20 LTS

---

## 🔧 Integration With Claude

### Step 1 — Backup original Claude

macOS / Linux / WSL:

```bash
mv $(which claude) $(dirname $(which claude))/claude-original
```

Windows PowerShell:

```powershell
Rename-Item (Get-Command claude).Source claude-original
```

---

### Step 2 — Activate wrapper

Add alias:

```bash
alias claude="private-context"
```

Reload shell:

```bash
source ~/.zshrc
# or
source ~/.bashrc
```

Done.

---

## 🖥 WSL Installation Notes

Important:

* Install Node inside WSL
* Install package inside WSL
* Backup Claude inside WSL
* Do not mix Windows Node with WSL Node

Everything must live in the same environment.

---

## 📁 Storage Location

```
~/.claude/private-context.db
```

SQLite database with FTS5 enabled.

---

## 🏗 Architecture Overview

Layered design:

* CLI Wrapper
* Core Engine
* SQLite Adapter
* Search Engine (FTS5)
* Context Injector
* Auto-prune Manager

Fully local.
No network dependency.
Deterministic behavior.

---

## 📊 Manual Context vs private-context

| Feature             | Manual | private-context |
| ------------------- | ------ | --------------- |
| Persistent Memory   | ❌      | ✅               |
| Automatic Injection | ❌      | ✅               |
| Semantic Retrieval  | ❌      | ✅               |
| Recency Ranking     | ❌      | ✅               |
| Auto-Prune          | ❌      | ✅               |
| Setup Complexity    | Medium | Low             |

---

## 🔄 Updating

```bash
npm update -g @septum-jdr/private-context
```

---

## ❌ Uninstall

Restore original Claude:

macOS / Linux / WSL:

```bash
mv $(dirname $(which claude))/claude-original $(dirname $(which claude))/claude
```

PowerShell:

```powershell
Rename-Item claude-original claude
```

Then:

```bash
npm uninstall -g @septum-jdr/private-context
```

---

## 🛡 Security

* Local-only storage
* No external APIs
* No telemetry
* No remote calls
* Fully auditable source

---

## 🧹 Auto-Prune Policy

Keeps last 500 entries automatically.

Prevents database bloat.

No manual maintenance required.

---

## 🧪 Troubleshooting

### "private-context ACTIVE" not showing

* Check alias
* Confirm correct Node environment
* Verify Claude binary was backed up correctly

### WSL not working

* Ensure Node and Claude are installed inside WSL
* Check `$HOME` path consistency

---

## 📈 Roadmap

* Configurable prune strategy
* Optional embeddings mode
* Context size visualization
* Session tagging
* Multi-project indexing

---

## 🤝 Contributing

PRs welcome.

1. Fork repository
2. Create feature branch
3. Submit PR

---

## 📜 License

MIT

---

## 👨‍💻 Author

```
@septum-jdr
```