Persistent Memory

Kognisant's memory system is what separates it from every other AI CLI tool. Instead of starting fresh each session, Kognisant builds and maintains a living knowledge base that compounds over time.

The Two-Layer Memory System

Kognisant uses a dual-layer approach that separates project-specific knowledge from universal knowledge.

Layer 1: Local Memory (per project)

Location: .kognisant/context.md in your project root

This is the "Membrain" for a single project. It stores:

Every time you start a chat session inside a project, Kognisant loads this file into its system prompt. The AI reads it before responding to any message, giving it full project awareness.

Example context.md:

# Project: my-rest-api

Architecture
FastAPI backend with SQLAlchemy ORM
PostgreSQL database, Redis for caching
JWT-based authentication

Current Phase
Building rate limiting middleware

Active Tasks
[x] Design rate limiter interface
[x] Implement sliding window counter
[ ] Add Redis backend for distributed limiting
[ ] Write integration tests

Key Decisions
Chose sliding window over token bucket (simpler for our scale)
Rate limits stored in Redis, not in-memory (need multi-instance support)

Layer 2: Global Memory (cross-project)

Location: ~/.kognisant_core/

This is the universal intelligence layer shared across all your projects. It contains:

---

Skills: Steering AI Behavior

Skills are markdown files in ~/.kognisant_core/skills/ that shape how Kognisant approaches tasks. They are loaded into every session's system prompt.

Default Skills (ship with Kognisant)

Creating Custom Skills

Create any .md file in the skills directory:

# Create a skill that teaches Kognisant your team's conventions
cat > ~/.kognisant_core/skills/team_conventions.md << 'EOF'
Team Coding Conventions

Naming
Use snake_case for Python files and functions
Use PascalCase for classes
Prefix private methods with underscore

Testing
Every public function needs at least one test
Use pytest fixtures, not setUp/tearDown
Mock external services, never hit real APIs in tests

Git
Commits follow conventional commits format
Feature branches: feature/short-description
Always squash merge to main
EOF

Once saved, this skill is automatically loaded in your next session. You will see it reflected in the ⚡ line:

⚡ gemma4:latest | valence: +15 | 4 skills, 4 tools

Viewing Loaded Skills

Inside a chat session:

/skills

This shows all active skills with their names and descriptions.

---

How Memory Compounds Over Time

The magic happens through the combination of layers:

Each session builds on the last. The AI does not start from zero.

---

When Memory Updates Automatically

Memory updates happen during the Persist phase of the PERP execution pipeline. This phase runs after every successful response that:

The update is atomic: Kognisant writes to a temp file, syncs to disk, then renames over the target. If anything fails, the previous state is preserved.

What triggers a context.md update:

What does NOT trigger an update:

---

Manually Editing context.md

You can (and should) edit context.md directly. It is a plain markdown file. Common reasons to edit manually:

# Open in your editor
vim .kognisant/context.md

Or use any editor
code .kognisant/context.md

Kognisant reads this file fresh at the start of every session, so your changes take effect immediately next time you run kognisant chat.

Tips for effective context.md:

---

Viewing Memory In-Session

To see the current project memory without leaving your chat:

/context

This renders the full context.md contents directly in the terminal.

---

Memory vs. Chat History

These are separate concepts:

---

Global Core Directory Structure

Here is the full layout of ~/.kognisant_core/:

~/.kognisant_core/
├── skills/                  # Markdown knowledge files
│   ├── web_browser_steering.md
│   ├── coding_standards.md
│   └── global_tool_development.md
├── tools/                   # Dynamic tools (JSON schema + Python impl)
│   ├── search_web.json
│   ├── search_web.py
│   ├── browse_web_page.json
│   ├── browse_web_page.py
│   └── ...
├── scripts/                 # Daemon-schedulable scripts
├── logs/                    # Error and diagnostic logs
├── models_pool.json         # Provider and model configurations
├── projects.json            # Registry of all initialized projects
├── self_model.json          # Reliability, valence, circuit breakers
├── autonomy_config.json     # Graduated autonomy settings
└── goal_stats.json          # Goal acceptance/dismissal tracking

---

When to Use Each Layer